portage.util package


Module contents

class portage.util.ConfigProtect(myroot, protect_list, mask_list, case_insensitive=False)

Bases: object


Returns True if obj is protected, False otherwise. The caller must ensure that obj is normalized with a single leading slash. A trailing slash is optional for directories.


Update internal state for isprotected() calls. Nonexistent paths are ignored.

class portage.util.LazyItemsDict(*args, **kwargs)

Bases: portage.cache.mappings.UserDict

A mapping object that behaves like a standard dict except that it allows for lazy initialization of values via callable objects. Lazy items can be overwritten and deleted just as normal items.

class _LazyItem(func, pargs, kwargs, singleton)

Bases: object

addLazyItem(item_key, value_callable, *pargs, **kwargs)

Add a lazy item for the given key. When the item is requested, value_callable will be called with *pargs and **kwargs arguments.

addLazySingleton(item_key, value_callable, *pargs, **kwargs)

This is like addLazyItem except value_callable will only be called a maximum of 1 time and the result will be cached for future requests.

get(key, default=None)
pop(key, *args)
setdefault(key, default=None)
update(*args, **kwargs)
portage.util._do_stat(filename, follow_links=True)
class portage.util._getconfig_shlex(portage_tolerant=False, **kwargs)

Bases: shlex.shlex

error_leader(infile=None, lineno=None)

Emit a C-compiler-like, Emacs-friendly error-message leader.


Get a token from the input stream (or from stack if it’s nonempty)


Pop the input source stack.

property punctuation_chars
push_source(newstream, newfile=None)

Push an input source onto the lexer’s input source stack.


Push a token onto the stack popped by the get_token method


Hook called on a filename to be sourced.

portage.util.append_repo(atom_list, repo_name, remember_source_file=False)

Takes a list of valid atoms without repo spec and appends ::repo_name. If an atom already has a repo part, then it is preserved (see bug #461948).

portage.util.apply_permissions(filename, uid=- 1, gid=- 1, mode=- 1, mask=- 1, stat_cached=None, follow_links=True)

Apply user, group, and mode bits to a file if the existing bits do not already match. The default behavior is to force an exact match of mode bits. When mask=0 is specified, mode bits on the target file are allowed to be a superset of the mode argument (via logical OR). When mask>0, the mode bits that the target file is allowed to have are restricted via logical XOR. Returns True if the permissions were modified and False otherwise.

portage.util.apply_recursive_permissions(top, uid=- 1, gid=- 1, dirmode=- 1, dirmask=- 1, filemode=- 1, filemask=- 1, onerror=None)

A wrapper around apply_secpass_permissions that applies permissions recursively. If optional argument onerror is specified, it should be a function; it will be called with one argument, a PortageException instance. Returns True if all permissions are applied and False if some are left unapplied.

portage.util.apply_secpass_permissions(filename, uid=- 1, gid=- 1, mode=- 1, mask=- 1, stat_cached=None, follow_links=True)

A wrapper around apply_permissions that uses secpass and simple logic to apply as much of the permissions as possible without generating an obviously avoidable permission exception. Despite attempts to avoid an exception, it’s possible that one will be raised anyway, so be prepared. Returns True if all permissions are applied and False if some are left unapplied.

portage.util.apply_stat_permissions(filename, newstat, **kwargs)

A wrapper around apply_secpass_permissions that gets uid, gid, and mode from a stat object

class portage.util.atomic_ofstream(filename, mode='w', follow_links=True, **kargs)

Bases: contextlib.AbstractContextManager, portage.proxy.objectproxy.ObjectProxy

Write a file atomically via os.rename(). Atomic replacement prevents interprocess interference and prevents corruption of the target file when the write is interrupted (for example, when an ‘out of space’ error occurs).

_abc_impl = <_abc._abc_data object>

If an error occurs while writing the file, the user should call this method in order to leave the target file unchanged. This will call close() automatically.


Closes the temporary file, copies permissions (if possible), and performs the atomic replacement via os.rename(). If the abort() method has been called, then the temp file is closed and removed.

class portage.util.cmp_sort_key(cmp_func)

Bases: object

In python-3.0 the list.sort() method no longer has a “cmp” keyword argument. This class acts as an adapter which converts a cmp function into one that’s suitable for use as the “key” keyword argument to list.sort(), making it easier to port code for python-3.0 compatibility. It works by generating key objects which use the given cmp function to implement their __lt__ method.

Beginning with Python 2.7 and 3.2, equivalent functionality is provided by functools.cmp_to_key().

class _cmp_key(cmp_func, obj)

Bases: object

portage.util.dump_traceback(msg, noiselevel=1)
portage.util.ensure_dirs(dir_path, **kwargs)

Create a directory and call apply_permissions. Returns True if a directory is created or the permissions needed to be modified, and False otherwise.

This function’s handling of EEXIST errors makes it useful for atomic directory creation, in which multiple processes may be competing to create the same directory.

portage.util.find_updated_config_files(target_root, config_protect)

Return a tuple of configuration files that needs to be updated. The tuple contains lists organized like this:

[protected_dir, file_list]

If the protected config isn’t a protected_dir but a procted_file, list is:

[protected_file, None]

If no configuration files needs to be updated, None is returned

portage.util.getconfig(mycfg, tolerant=False, allow_sourcing=False, expand=True, recursive=False)
portage.util.getlibpaths(root, env=None)
portage.util.grabdict(myfilename, juststrings=0, empty=0, recursive=0, incremental=1, newlines=0)

This function grabs the lines in a file, normalizes whitespace and returns lines in a dictionary

  • myfilename (string (path)) – file to process

  • juststrings (Boolean (integer)) – only return strings

  • empty (Boolean (integer)) – Ignore certain lines

  • recursive (Boolean (integer)) – Recursively grab ( support for /etc/portage/package.keywords/* and friends )

  • incremental (Boolean (integer)) – Append to the return list, don’t overwrite

  • newlines (Boolean (integer)) – Append newlines

Return type



  1. Returns the lines in a file in a dictionary, for example:

    ‘sys-apps/portage x86 amd64 ppc’ would return {“sys-apps/portage” : [‘x86’, ‘amd64’, ‘ppc’]}

portage.util.grabdict_package(myfilename, juststrings=0, recursive=0, newlines=0, allow_wildcard=False, allow_repo=False, allow_build_id=False, allow_use=True, verify_eapi=False, eapi=None, eapi_default='0')

Does the same thing as grabdict except it validates keys with isvalidatom()

portage.util.grabfile(myfilename, compat_level=0, recursive=0, remember_source_file=False)

This function grabs the lines in a file, normalizes whitespace and returns lines in a list; if a line begins with a #, it is ignored, as are empty lines

portage.util.grabfile_package(myfilename, compatlevel=0, recursive=0, allow_wildcard=False, allow_repo=False, allow_build_id=False, remember_source_file=False, verify_eapi=False, eapi=None, eapi_default='0')
portage.util.grablines(myfilename, recursive=0, remember_source_file=False)

Sets up basic logging of portage activities Args:

level: the level to emit messages at (‘info’, ‘debug’, ‘warning’ …)



portage.util.map_dictlist_vals(func, myDict)

Performs a function on each value of each key in a dictlist. Returns a new dictlist.

portage.util.new_protect_filename(mydest, newmd5=None, force=False)

Resolves a config-protect filename for merging, optionally using the last filename if the md5 matches. If force is True, then a new filename will be generated even if mydest does not exist yet. (dest,md5) ==> ‘string’ — path_to_target_filename (dest) ==> (‘next’, ‘highest’) — next_target and most-recent_target


os.path.normpath(“//foo”) returns “//foo” instead of “/foo” We dislike this behavior so we create our own normpath func to fix it.

portage.util.pickle_read(filename, default=None, debug=0)
portage.util.read_corresponding_eapi_file(filename, default='0')

Read the ‘eapi’ file from the directory ‘filename’ is in. Returns “0” if the file is not present or invalid.


This is equivalent to shlex.split, but if the current interpreter is python2, it temporarily encodes unicode strings to bytes since python2’s shlex.split() doesn’t handle unicode strings.

portage.util.stack_dictlist(original_dicts, incremental=0, incrementals=[], ignore_none=0)

Stacks an array of dict-types into one array. Optionally merging or overwriting matching key/value pairs for the dict[key]->list. Returns a single dict. Higher index in lists is preferenced.

Example usage:
>>> from portage.util import stack_dictlist
     >>> print stack_dictlist( [{'a':'b'},{'x':'y'}])
     >>> {'a':'b','x':'y'}
     >>> print stack_dictlist( [{'a':'b'},{'a':'c'}], incremental = True )
     >>> {'a':['b','c'] }
     >>> a = {'KEYWORDS':['x86','alpha']}
     >>> b = {'KEYWORDS':['-x86']}
     >>> print stack_dictlist( [a,b] )
     >>> { 'KEYWORDS':['x86','alpha','-x86']}
     >>> print stack_dictlist( [a,b], incremental=True)
     >>> { 'KEYWORDS':['alpha'] }
     >>> print stack_dictlist( [a,b], incrementals=['KEYWORDS'])
     >>> { 'KEYWORDS':['alpha'] }

:param original_dicts a list of (dictionary objects or None) :type list :param incremental True or false depending on whether new keys should overwrite

keys which already exist.

:type boolean :param incrementals A list of items that should be incremental (-foo removes foo from

the returned dict).

:type list :param ignore_none Appears to be ignored, but probably was used long long ago. :type boolean

portage.util.stack_dicts(dicts, incremental=0, incrementals=[], ignore_none=0)

Stacks an array of dict-types into one array. Optionally merging or overwriting matching key/value pairs for the dict[key]->string. Returns a single dict.

portage.util.stack_lists(lists, incremental=1, remember_source_file=False, warn_for_unmatched_removal=False, strict_warn_for_unmatched_removal=False, ignore_repo=False)

Stacks an array of list-types into one array. Optionally removing distinct values using ‘-value’ notation. Higher index is preferenced.

all elements must be hashable.


lifted from python cookbook, credit: Tim Peters Return a list of the elements in s in arbitrary order, sans duplicates

portage.util.unique_everseen(iterable, key=None)

List unique elements, preserving order. Remember all elements ever seen. Taken from itertools documentation.

portage.util.varexpand(mystring, mydict=None, error_leader=None)
portage.util.write_atomic(file_path, content, **kwargs)
portage.util.writedict(mydict, myfilename, writekey=True)

Writes out a dict to a file; writekey=0 mode doesn’t write out the key and assumes all values are strings, not lists.

portage.util.writemsg(mystr, noiselevel=0, fd=None)

Prints out warning and debug messages based on the noiselimit setting

portage.util.writemsg_level(msg, level=0, noiselevel=0)

Show a message for the given level as defined by the logging module (default is 0). When level >= logging.WARNING then the message is sent to stderr, otherwise it is sent to stdout. The noiselevel is passed directly to writemsg().

  • msg (str) – a message string, including newline if appropriate

  • level (int) – a numeric logging level (see the logging module)

  • noiselevel (int) – passed directly to writemsg

portage.util.writemsg_stdout(mystr, noiselevel=0)

Prints messages stdout based on the noiselimit setting