dockermap package

Subpackages

Submodules

dockermap.api module

dockermap.dep module

class dockermap.dep.BaseDependencyResolver

Bases: object

Base class for resolving dependencies of hierarchical nodes. Not each node has to be relevant, and on each level parent dependencies can be merged with the current node.

get(item)

Returns the direct dependencies or dependents of a single item. Does not follow the entire dependency path.

Parameters:item – Node to return dependencies for.
Returns:Immediate dependencies or dependents.
get_default()

Defines a return value if an item is not found on the dependency map or does not have any dependencies.

Returns:Default value.
get_dependencies(item)

Performs a dependency check on the given item.

Parameters:item – Node to start the dependency check with.
Returns:The result on merged dependencies down the hierarchy.
merge_dependency(item, resolve_parent, parent)
reset()

Resets all cached nodes.

update(items)
class dockermap.dep.CachedDependency(parent, dependencies=<class 'dockermap.dep.NotInitialized'>)

Bases: object

Caching dependencies along the hierarchy.

dependencies

Boolean, list, or other representation of cached dependencies from the parent. Returns NotInitialized if not cached yet.

parent

Parent node(s).

exception dockermap.dep.CircularDependency(item, is_direct=False, *args, **kwargs)

Bases: exceptions.Exception

Indicates that dependencies cannot be resolved, since items are interdependent.

is_direct
item
class dockermap.dep.ImageDependentsResolver(initial=None)

Bases: dockermap.dep.BaseDependencyResolver

merge_dependency(item, resolve_parent, parents)

Merge dependencies of element with further dependencies. First parent dependencies are checked, and then immediate dependencies of the current element should be added to the list, but without duplicating any entries.

Parameters:
  • item – Item.
  • resolve_parent (function) – Function to resolve parent dependencies.
Returns:

List of recursively resolved dependencies of this container.

Return type:

list

Raises:

CircularDependency – If the current element depends on one found deeper in the hierarchy.

update(items)

Updates the dependencies in the inverse relationship format, i.e. from an iterable or dict that is structured as (item, dependent_items). Note that this implementation is only valid for 1:1 relationships, i.e. that each node has also exactly one dependent. For other cases, MultiDependencyResolver should be used.

Parameters:items (collections.Iterable) – Iterable or dictionary in the format (item, dependent_items).
class dockermap.dep.MultiForwardDependencyResolver(initial=None)

Bases: dockermap.dep.BaseDependencyResolver

Abstract, partial implementation of a dependency resolver for nodes in a m:n relationship, i.e. that each node depends on one or multiple items.

update(items)

Updates the dependencies with the given items. Note that this does not reset all previously-evaluated and cached nodes.

Parameters:items (collections.Iterable) – Iterable or dictionary in the format (dependent_item, dependencies).
class dockermap.dep.MultiReverseDependencyResolver(initial=None)

Bases: dockermap.dep.BaseDependencyResolver

update(items)

Updates the dependencies in the inverse relationship format, i.e. from an iterable or dict that is structured as (item, dependent_items). The parent element item may occur multiple times.

Parameters:items (collections.Iterable) – Iterable or dictionary in the format (item, dependent_items).
class dockermap.dep.NotInitialized

Bases: object

Utility class to locate nodes in the dependency tree where there is no cached dependency structure yet.

dockermap.docker_api module

dockermap.exceptions module

exception dockermap.exceptions.DockerStatusError(message, detail)

Bases: exceptions.Exception

detail
message
exception dockermap.exceptions.PartialResultsError(src_exc, *args, **kwargs)

Bases: dockermap.exceptions.SourceExceptionMixin, dockermap.exceptions.PartialResultsMixin, exceptions.Exception

Exception where partial results might be available.

class dockermap.exceptions.PartialResultsMixin(partial_results, *args, **kwargs)

Bases: object

results

Partial results before the exception occurred.

Returns:list
class dockermap.exceptions.SourceExceptionMixin(src_exc, *args, **kwargs)

Bases: object

reraise()

Utility method for re-raising the original exception, including output of its stacktrace.

source_exception

The original exception information from where the error occurred. Tuple of exception type and exception instance (e.g. the output of sys.exc_info()).

Returns:Exception tuple.
Return type:tuple
source_message

Formatted output of the exception, without the stack trace.

Returns:Exception text.
Return type:unicode | str

dockermap.functional module

class dockermap.functional.AbstractLazyObject(func, *args, **kwargs)

Bases: object

Abstract superclass class for lazily-resolved values. Runs function func with *args and **kwargs, when called or the get function is used. The following also trigger an evaluation:

  • String representation.
  • Equality or inequality check.
  • Contains operator.
  • Iteration.
  • Reduce (pickling).
Parameters:
  • func (callable) – Callable to evaluate.
  • args – Arguments to pass to func.
  • kwargs – Keyword arguments to pass to func.
args

Positional arguments for func.

Returns:Positional arguments.
Return type:tuple
func

Callable to run for evaluation.

Returns:Callable.
Return type:callable
get()
kwargs

Keyword arguments for func.

Returns:Keyword arguments.
Return type:dict
value

Resolved and and returns the value.

Returns:The actual value, resolved by the object.
class dockermap.functional.LazyOnceObject(func, *args, **kwargs)

Bases: dockermap.functional.AbstractLazyObject

Like SimpleLazyObject, but runs the evaluation only once. Note that even None will be re-used as a valid result.

Parameters:
  • func (callable) – Callable to evaluate.
  • args – Arguments to pass to func.
  • kwargs – Keyword arguments to pass to func.
evaluated

Indicates whether the object has been evaluated before.

Returns:Returns True in case the object has been evaluated, False otherwise.
get()

Resolves and returns the object value. Re-uses an existing previous evaluation, if applicable.

Returns:The result of evaluating the object.
class dockermap.functional.SimpleLazyObject(func, *args, **kwargs)

Bases: dockermap.functional.AbstractLazyObject

Simple lazy-resolving object.

get()

Resolves and returns the object value.

Returns:The result of evaluating the object.
dockermap.functional.expand_type_name(type_)

Returns concatenated module and name of a type for identification.

Parameters:type (type) – Type:
Returns:Type name, as <type's module name>.<type name>.
Return type:unicode | str
dockermap.functional.lazy

alias of SimpleLazyObject

dockermap.functional.lazy_once

alias of LazyOnceObject

dockermap.functional.lazy_type

alias of AbstractLazyObject

dockermap.functional.register_type(resolve_type, resolve_func)

Registers a type for lazy value resolution. Instances of AbstractLazyObject do not have to be registered. The exact type must be provided in resolve_type, not a superclass of it. Types registered will be passed through the given function by resolve_value().

Parameters:
  • resolve_type (type) – Type to consider during late value resolution.
  • resolve_func (function) – Function to run for retrieving the original value. It needs to accept exactly one argument - the substitute value to resolve to the actual value.
dockermap.functional.resolve_deep(values, max_depth=5, types=None)

Resolves all late-resolving types into their current values to a certain depth in a dictionary or list.

Parameters:
  • values – Values to resolve of any type.
  • max_depth (int) – Maximum depth to recurse into nested lists, tuples and dictionaries. Below that depth values are returned as they are.
Param:

Dictionary of types and functions to resolve, that are not registered in type_registry.

Type:

dict[unicode | str, function]

Returns:

Resolved values.

dockermap.functional.resolve_value(value, types={})

Returns the actual value for the given object, if it is a late-resolving object type. If not, the value itself is simply returned.

Parameters:value (str | unicode | int | AbstractLazyObject | unknown) – Lazy object, registered type in type_registry, or a simple value. In the latter case, the value is returned as-is.
Returns:Resolved value.
dockermap.functional.uses_type_registry(value)

Utility function to check whether a certain value would be handled by late value resolution. This does not check lazy objects, but only explicitly registered types.

Parameters:value – Value to check.
Returns:Whether the type of the given value is registered.
Return type:bool

dockermap.shortcuts module

dockermap.shortcuts.addgroup(groupname, gid, system=False)
dockermap.shortcuts.addgroupuser(username, uid, groupnames=None, system=False, no_login=True, no_password=False, gecos=None, sudo=False, **kwargs)

Generates a unix command line for creating user and group with the same name, assigning the user to the group. Has the same effect as combining addgroup(), adduser(), and assignuser().

Parameters:
  • username (unicode | str) – User name to create.
  • uid (int) – User id to use.
  • groupnames (collections.Iterable[unicode | str]) – Iterable with additional group names to assign the user to.
  • system (bool) – Create a system user and group. Default is False.
  • no_login (bool) – Disallow login of this user and group, and skip creating the home directory. Default is True.
  • no_password – Do not set a password for the new user.
  • gecos (unicode | str) – Provide GECOS info and suppress prompt.
  • sudo (bool) – Prepend sudo to the command. Default is False. When using Fabric, use its sudo command instead.
  • kwargs – Additional keyword arguments for command line arguments.
Type:

no_password: bool

Returns:

Unix shell command line.

Return type:

unicode | str

dockermap.shortcuts.adduser(username, uid=None, system=False, no_login=True, no_password=False, group=False, gecos=None, **kwargs)

Formats an adduser command.

Parameters:
  • username (unicode | str) – User name.
  • uid (long | int) – Optional user id to use.
  • system (bool) – Create a system user account.
  • no_login (bool) – Disable the login for this user. Not compatible with CentOS. Implies setting ‘–no-create-home’, and no_password.
  • no_password (bool) – Disable the password for this user. Not compatible with CentOS.
  • group (bool) – Create a group along with the user. Not compatible with CentOS.
  • gecos (unicode | str) – Set GECOS information in order to suppress an interactive prompt. On CentOS, use __comment instead.
  • kwargs – Additional keyword arguments which are converted to the command line.
Returns:

A formatted adduser command with arguments.

Return type:

unicode | str

dockermap.shortcuts.assignuser(username, groupnames)
dockermap.shortcuts.chmod(mode, path, recursive=True)
dockermap.shortcuts.chown(user_group, path, recursive=True)
dockermap.shortcuts.curl(url, filename=None)
dockermap.shortcuts.get_user_group(user_group)

Formats a user and group in the format user:group, as needed for chown. If user_group is a tuple, this is used for the fomatting. If a string or integer is given, it will be formatted as user:user. Otherwise the input is returned - this method does not perform any more checks.

Parameters:user_group (unicode | str | int | tuple) – User name, user id, user and group in format user:group, user_id:group_id, or tuple of (user, group).
Returns:Formatted string with in the format user:group.
Return type:unicode | str
dockermap.shortcuts.mkdir(path, create_parent=True, check_if_exists=False)

Generates a unix command line for creating a directory.

Parameters:
  • path (unicode | str) – Directory path.
  • create_parent (bool) – Create parent directories, if necessary. Default is True.
  • check_if_exists (bool) – Prepend a check if the directory exists; in that case, the command is not run. Default is False.
Returns:

Unix shell command line.

Return type:

unicode | str

dockermap.shortcuts.mkdir_chown(paths, user_group=None, permissions=u'ug=rwX, o=rX', create_parent=True, check_if_exists=False, recursive=False)

Generates a unix command line for creating a directory and assigning permissions to it. Shortcut to a combination of mkdir(), chown(), and chmod().

Note that if check_if_exists has been set to True, and the directory is found, mkdir is not called, but user_group and permissions are still be applied.

Parameters:
  • paths (unicode | str | tuple[unicode | str] | list[unicode | str]) – Can be a single path string, or a list or tuple of path strings.
  • permissions (unicode | str) – Optional permission mode, in any notation accepted by the unix chmod command. Default is ug=rwX,o=rX.
  • create_parent (bool) – Parent directories are created if not present (-p argument to mkdir).
  • check_if_exists (bool) – Prior to creating the directory, checks if it already exists.
  • recursive (bool) – Apply permissions and owner change recursively.
Param:

Optional owner of the directory. For notation, see get_user_group().

Returns:

Unix shell command line.

Return type:

unicode | str

dockermap.shortcuts.rm(path, recursive=False, force=False)
dockermap.shortcuts.str_arg(arg)
dockermap.shortcuts.targz(filename, source)
dockermap.shortcuts.untargz(filename, target=None)
dockermap.shortcuts.wget(url, filename=None)

dockermap.utils module

dockermap.utils.expand_path(value)
dockermap.utils.expand_path_lazy(value)
dockermap.utils.format_image_tag()

S.format(*args, **kwargs) -> unicode

Return a formatted version of S, using substitutions from args and kwargs. The substitutions are identified by braces (‘{‘ and ‘}’).

dockermap.utils.merge_list(merged_list, items)

Merges items into a list, appends ignoring duplicates but retaining the original order. This modifies the list and does not return anything.

Parameters:
  • merged_list (list) – List to append de-duplicated items to.
  • items (collections.Iterable) – Items to merge into the list.

Module contents