wiz.definition¶

wiz.definition.fetch(paths, system_mapping=None, max_depth=None)[source]¶

Return mapping from all definitions available under paths.

A definition mapping should be in the form of:

{
    "command": {
        "fooExe": "foo",
        ...
    },
    "package": {
        "__namespace__": {
            "bar": {"test"}
        },
        "foo": {
            "1.1.0": <Definition(identifier="foo", version="1.1.0")>,
            "1.0.0": <Definition(identifier="foo", version="1.0.0")>,
            "0.1.0": <Definition(identifier="foo", version="0.1.0")>,
            ...
        },
        "test::bar": {
            "0.1.0": <Definition(identifier="bar", version="0.1.0")>,
            ...
        },
        ...
    },
    "implicit-packages": [
        "bar==0.1.0",
        ...
    ]
}

Parameters:	paths – List of registry paths to recursively fetch `definitions` from. system_mapping – Mapping defining the current system to filter out non compatible definitions. Default is None, which means that the current system mapping will be `queried`. max_depth – Limited recursion value to search for `definitions`. Default is None, which means that all sub-trees will be visited.
Returns:	Definition mapping.

wiz.definition.query(requirement, definition_mapping, namespace_counter=None)[source]¶

Return best matching definition version from requirement.

Parameters:	requirement – Instance of `packaging.requirements.Requirement`. definition_mapping – Mapping regrouping all available definitions associated with their unique identifier. namespace_counter – instance of `collections.Counter` which indicates occurrence of namespaces used as hints for package identification. Default is None.
Returns:	Instance of `Definition`.
Raise:	`wiz.exception.RequestNotFound` if the requirement can not be resolved.

wiz.definition.export(path, data, overwrite=False)[source]¶

Export definition as a JSON file to path.

Parameters:	path – Target path to save the exported definition into. data – Instance of `wiz.definition.Definition` or a mapping in the form of: { "identifier": "foo", "description": "This is my package", "version": "0.1.0", "command": { "app": "AppExe", "appX": "AppExe --mode X" }, "environ": { "KEY1": "value1", "KEY2": "value2" }, "requirements": [ "package1 >=1, <2", "package2" ] } overwrite – Indicate whether existing definitions in the target path will be overwritten. Default is False.
Returns:	Path to exported definition.
Raise:	`wiz.exception.IncorrectDefinition` if data is a mapping that cannot create a valid instance of `wiz.definition.Definition`.
Raise:	`wiz.exception.FileExists` if definition already exists in path and overwrite is False.
Raise:	`OSError` if the definition can not be exported in path.

Warning

Ensure that the data identifier, namespace, version and system requirement are unique in the registry.

Each command must also be unique in the registry.

wiz.definition.discover(paths, system_mapping=None, max_depth=None)[source]¶

Discover and yield all definitions found under paths.

Parameters:	paths – List of registry paths to recursively fetch `definitions` from. system_mapping – Mapping of the current system which will filter out non compatible definitions. The mapping should have been retrieved via `wiz.system.query()`. max_depth – Limited recursion value to search for `definitions`. Default is None, which means that all sub-trees will be visited.
Returns:	Generator which yield all `definitions`.

wiz.definition.load(path, mapping=None, registry_path=None)[source]¶

Load and return a definition from path.

Parameters:	path – JSON file path which contains a definition. mapping – Mapping which will augment the data leading to the creation of the definition. Default is None. registry_path – Path to the registry which contains the definition. Default is None.
Returns:	Instance of `Definition`.
Raise:	`wiz.exception.IncorrectDefinition` if the definition is incorrect.

class wiz.definition.Definition(data, path=None, registry_path=None, copy_data=True)[source]¶

Definition object.

__init__(data, path=None, registry_path=None, copy_data=True)[source]¶

Initialize definition from input data mapping.

Parameters:	data – Data definition mapping. path – Path to the definition JSON file used to create the definition if available. Default is None. registry_path – Path to the registry from which the definition where fetched if available. Default is None. copy_data – Indicate whether input data will be copied to prevent mutating it. Default is True.
Raise:	`wiz.exception.IncorrectDefinition` if the data mapping is incorrect.

Warning

“requirements” and “conditions” values will not get validated when constructing the instance for performance reason. Therefore, accessing these values could raise an error when data is incorrect:

>>> definition = Definition({
...     "identifier": "foo",
...     "requirements": ["!!!"],
... })
>>> print(definition.requirements)

InvalidRequirement: The requirement '!!!' is incorrect

See also

Using Package Definitions

path¶

Return path to definition if available.

Returns:	Definition JSON path or None.

registry_path¶

Return registry path containing the definition if available.

Returns:	Registry path or None.

identifier¶

Return definition identifier.

Returns:	String value (e.g. “foo”).

See also

Identifier

version¶

Return definition version.

Returns:	Instance of `packaging.version.Version` or None.
Raise:	`wiz.exception.InvalidVersion` if the version is incorrect.

Note

The value is cached when accessed once to ensure faster access afterwards.

See also

Version

qualified_identifier¶

Return qualified identifier with optional namespace.

Returns:	String value (e.g. “namespace::foo”).

version_identifier¶

Return version identifier.

Returns:	String value (e.g. “foo==0.1.0”).

qualified_version_identifier¶

Return qualified version identifier with optional namespace.

Returns:	String value (e.g. “namespace::foo==0.1.0”).

description¶

Return definition description.

Returns:	String value or None.

See also

Description

namespace¶

Return definition namespace.

Returns:	String value or None.

See also

Namespace

auto_use¶

Return whether definition should be automatically requested.

Returns:	Boolean value.

See also

Auto Use

disabled¶

Return whether definition is disabled.

Returns:	Boolean value.

See also

Disabled

install_root¶

Return root installation path.

Returns:	Directory path or None.

See also

Install Root

install_location¶

Return installation path.

Returns:	Directory path or None.

See also

Install Location

environ¶

Return environment variable mapping.

Returns:	Dictionary value.

See also

Environment

command¶

Return command mapping.

Returns:	Dictionary value.

See also

Commands

system¶

Return system requirement mapping.

Returns:	Dictionary value.

See also

System

requirements¶

Return list of requirements.

Returns:	List of `packaging.requirements.Requirement` instances.
Raise:	`wiz.exception.InvalidRequirement` if one requirement is incorrect.

Note

The value is cached when accessed once to ensure faster access afterwards.

See also

Requirements

conditions¶

Return list of conditions.

Returns:	List of `packaging.requirements.Requirement` instances.
Raise:	`wiz.exception.InvalidRequirement` if one requirement is incorrect.

Note

The value is cached when accessed once to ensure faster access afterwards.

See also

Conditions

variants¶

Return list of conditions.

Returns:	List of `Variant` instances.

Note

The value is cached when accessed once to ensure faster access afterwards.

See also

Variants

set(element, value)[source]¶

Returns copy of instance with element set to value.

Parameters:	element – Keyword to add or update in mapping. value – New value to set as keyword value.
Returns:	New updated mapping.

update(element, value)[source]¶

Returns copy of instance with element mapping updated with value.

Parameters:	element – keyword associated to a dictionary. value – mapping to update element dictionary with.
Returns:	New updated mapping.
Raise:	`ValueError` if element is not a dictionary.

extend(element, values)[source]¶

Returns copy of instance with element list extended with values.

Parameters:	element – keyword associated to a list. values – Values to extend element list with.
Returns:	New updated mapping.
Raise:	`ValueError` if element is not a list.

insert(element, value, index)[source]¶

Returns copy of instance with value inserted in element list.

Parameters:	element – keyword associated to a list. value – Value which will be added to the element list index – Index number at which the value should be inserted.
Returns:	New updated mapping.
Raise:	`ValueError` if element is not a list.

remove(element)[source]¶

Returns copy of instance without element.

Parameters:	element – keyword to remove from mapping.
Returns:	New updated mapping or “self” if element didn’t exist in mapping.

remove_key(element, value)[source]¶

Returns copy of instance without key value from element mapping.

If element mapping is empty after removing value, the element key will be removed.

Parameters:	element – keyword associated to a dictionary. value – Value to remove from element dictionary.
Returns:	New updated mapping.
Raise:	`ValueError` if element is not a dictionary.

remove_index(element, index)[source]¶

Returns copy of instance without index from element list.

If element list is empty after removing index, the element key will be removed.

Parameters:	element – keyword associated to a list. index – Index to remove from element list.
Returns:	New updated mapping.
Raise:	`ValueError` if element is not a list.

data(copy_data=True)[source]¶

Return definition data used to created the definition instance.

Parameters:	copy_data – Indicate whether definition data will be copied to prevent mutating it. Default is True.
Returns:	Definition data mapping.

ordered_data(copy_data=True)[source]¶

Return copy of definition data as collections.OrderedDict.

Definition keywords will be sorted as follows:

identifier

version

namespace

description

install-root

install-location

auto-use

disabled

system

command

environ

requirements

conditions

variants

System keywords will be sorted as follows:

platform

os

arch

Each variant mapping will be sorted as follows:

identifier

install-location

command

environ

requirements

Parameters:	copy_data – Indicate whether definition data will be copied to prevent mutating it. Default is True.
Returns:	Instance of `collections.OrderedDict`.

encode()[source]¶

Return serialized definition data.

collections.OrderedDict instance as returned by ordered_data() is being used.

Returns:	Serialized mapping.

class wiz.definition.Variant(data, definition_identifier)[source]¶

Definition variant object.

__init__(data, definition_identifier)[source]¶

Initialize definition variant.

Parameters:	data – Variant data definition mapping. definition_identifier – Identifier of the definition containing the variant data.

Warning

“requirements” values will not get validated when constructing the instance for performance reason. Therefore, accessing this value could raise an error when data is incorrect:

>>> variant = Variant(
...     {
...         "identifier": "variant1",
...         "requirements": ["!!!"],
...     },
...     definition_identifier="foo"
... )
>>> print(variant.requirements)

InvalidRequirement: The requirement '!!!' is incorrect

See also

Variants

identifier¶

Return variant identifier.

Returns:	String value (e.g. “variant1”).

definition_identifier¶

Return definition identifier.

Returns:	String value (e.g. “foo”).

install_location¶

Return installation path.

Returns:	Directory path or None.

See also

Install Location

environ¶

Return environment variable mapping.

Returns:	Dictionary value.

See also

Environment

command¶

Return command mapping.

Returns:	Dictionary value.

See also

Commands

requirements¶

Return list of requirements.

Returns:	List of `packaging.requirements.Requirement` instances.
Raise:	`wiz.exception.InvalidRequirement` if one requirement is incorrect.

Note

The value is cached when accessed once to ensure faster access afterwards.

See also

Requirements

data(copy_data=True)[source]¶

Return variant data used to created the variant instance.

Parameters:	copy_data – Indicate whether definition data will be copied to prevent mutating it. Default is True.
Returns:	Variant data mapping.