Migration notes

This section will show more detailed information when relevant for switching to a new version, such as when upgrading involves backwards incompatibilities.

Migrate to 3.6.0

API

wiz.validate_definition() has been removed as it was using unsafe logic modifying the logging configuration outside of the main program.

Migrate to 3.3.0

Exceptions

The following exceptions have been renamed for consistency:

API

The following functions have been removed as part of the refactoring process of wiz.graph:

  • wiz.graph.generate_variant_combinations()
  • wiz.graph.trim_unreachable_from_graph()
  • wiz.graph.updated_by_distance()
  • wiz.graph.validate()
  • wiz.graph.extract_ordered_packages()
  • wiz.graph.relink_parents()
  • wiz.graph.sanitize_requirement()

Migrate to 3.1.0

Command line

The command wiz install --registry has been renamed to wiz install --output to better differentiate the command from wiz --registry.

The short option -f has been added for --override. As a result, the followings commands have been renamed to prevent confusion:

  • wiz freeze -f/--format has been renamed to wiz freeze -F/--format
  • wiz analyze -f/--filter has been removed to set filters as non-required positional option instead.
avoid 
# Analyze all definitions whose identifiers matched "foo" or "bar"
>>> wiz analyze -f "foo" -f "bar"
prefer 
# Analyze all definitions whose identifiers matched "foo" or "bar"
>>> wiz analyze "foo" "bar"

API

The following functions have been renamed to use American spelling for consistency:

Validation API

The wiz.validator module has been modified to prevent using the jsonschema library which is based on JSON Schema validation as it was hindering the performance when creating an instance of wiz.definition.Definition.

Therefore, wiz.validator.yield_definition_errors() has been replaced by wiz.validator.validate_definition().

Definition API

The wiz.definition.Definition construction has been modified to simplify its usage and improve its instantiation speed.

avoid 
>>> Definition({
...    "identifier": "foo",
...    "definition-location": "/path/to/definition.json",
...    "registry": "/path/to/registry",
... })
prefer 
>>> Definition(
...     {"identifier": "foo"},
...     path="/path/to/definition.json",
...     registry_path="/path/to/registry",
... )

This change eliminates the need to sanitize the definition data before exporting. Therefore, wiz.definition.Definition.sanitized() has been removed.

The wiz.definition.Definition constructor is using the new custom validation function wiz.validator.validate_definition(). The following operations are now not performed during initialization, but will instead be cached the first time they are accessed:

An wiz.exception.InvalidRequirement error is raised when accessing incorrect requirements or conditions.

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

InvalidRequirement: The requirement '!!!' is incorrect

The wiz.definition.Definition class is no longer inheriting from collections.Mapping, so attributes are only accessible from properties as get() is no longer available.

Package API

The wiz.package.Package construction has been modified to simplify its usage and improve its instantiation speed. It does not inherit from collections.Mapping anymore and uses wiz.definition.Definition keywords instead of copying data.

avoid 
>>> Package({
...    "identifier": "foo[V1]==0.1.0",
...    "version": "0.1.0",
...    "variant-name": "V1",
... })
prefer 
>>> definition = Definition({
...    "identifier": "foo",
...    "version": "0.1.0",
...    "variants": [
...        {"identifier": "V1"}
...    ]
... })
>>> Package(definition, variant_index=0)

The wiz.package.Package.identifier() property has been updated to prepend Namespace to ensure that a unique identifier is always used. As a result, wiz.package.Package.qualified_identifier() has been removed.

Migrate to 3.0.0

project name

Project name has been changed to wiz-env to guarantee a unique name on Pypi.

configuration and plugins

Wiz is now customizable via configurations and plugins.

The user can define a custom configuration in ~/.wiz/config.toml as well as custom plugins in ~/.wiz/plugins, or overwrite these default during the installation process.

See also

Building with custom options

registries

Registry paths are no longer hard-coded in the package. wiz.registry.get_defaults() now returns the paths defined in the configuration mapping.

installation

The logic to install package definition is now defined by plugins. A default plugin is provided to install package definition to a registry path (installer.py).

The concept of a VCS Registry has been removed and should be taken care of by plugins.

These functions have been removed:

  • wiz.install_definitions()
  • wiz.registry.install_to_vcs()

initial environment

The initial environment is no longer hard-coded in the package but instead defined by configurations and plugins. wiz.environ.initiate() returns the mapping accordingly.

Migrate to 2.0.0

registries

The following commands have been renamed:

The registry paths can now be set as follow:

wiz -r /path/to/registry1 -r /path/to/registry2 use foo

The --add-registry command has been added in order to prepend a registry in front of discovered registries.

installation

The wiz install sub-command has been modified to regroup the –registry-path and –registry-id options into one –registry option which can be used as follow:

# For local registries
>>> wiz install foo.json --registry /path/to/registry
>>> wiz install foo.json -r /path/to/registry

# For VCS registries
>>> wiz install foo.json -registry wiz://primary-registry
>>> wiz install foo.json -r wiz://primary-registry

The –install-location option from the wiz install sub-command as been removed as editing the definition can be simply done via the new wiz edit sub-command.

The optional install-root keyword has been added to define a prefix path to the install-location

namespaces

The optional namespace keyword has been added to the definition in lieu of the previous “group” keyword which has been removed.

The “group” keyword was only used to precise the folder hierarchy within VCS Registry, whereas namespaces are actively used for the definition query and package extraction process.

conditions

The optional conditions keyword has been added to indicate a list of packages which must be in the resolution graph for a definition package to be include.

It replaces the “constraints” keyword as the same logic can be achieved with conditions instead.

With constraint:

{
    "constraints": [
        "maya ==2016.*"
    ]
}

With condition:

{
    "conditions": [
       "maya"
    ],
    "requirements": [
       "maya ==2016.*"
    ]
}

Warning

Update: It is not recommended to use conditions to lock down a package version as it will end up with an unsolvable graph most of the time.

implicit packages

Implicit packages identified by the auto-use keyword are now prepended to the list of explicit requests instead of being appended. It ensures that implicit packages have always higher priorities than explicit packages, which is necessary when being used within project registries to augment or overwrite environment variables.

Consider the following definitions:

{
   "identifier": "project",
   "auto-use": true,
   "environ": {
      "SHADER_PATH": "/jobs/ads/project/shaders:${SHADER_PATH}"
   }
}

{
   "identifier": "mtoa",
   "environ": {
      "SHADER_PATH": "/path/to/mtoa/shaders:${SHADER_PATH}"
   }
}

The command wiz use mtoa would previously resolve the SHADER_PATH environment variable as follow: /path/to/mtoa/shaders:/jobs/ads/project/shaders

It will now be resolved as follow: /jobs/ads/project/shaders:/path/to/mtoa/shaders

spawned shell

The “shell_type” optional argument has been removed from wiz.spawn.shell() as spawned shell will only support Bash for now.

API

The following functions have been renamed:

  • wiz.package.initiate_environ() → wiz.environ.initiate()
  • wiz.package.sanitise_environ_mapping() → wiz.environ.sanitise()

Package can now be instantiated with a simple mapping. A new wiz.package.create() function has been added to create packages from Definition instances.

wiz.package.generate_identifier() has been removed as this logic has been implemented in the following attributes:

Migrate to 1.0.0

The following functions / methods have been removed as part of a refactoring of the wiz.graph module:

  • wiz.graph.validate_requirements()
  • wiz.graph.extract_requirement()
  • wiz.graph.Graph.copy()

The wiz.graph.Graph constructor only need a wiz.graph.Resolver argument as its content should only rely on the wiz.graph.Graph.update_from_requirements() method.

A “priority” mapping was used in order to identify the shortest path of each node to the root level of the graph. However, a node with a lower “priority” has a higher importance in the graph, which can be confusing. Therefore the term “priority” has been replaced by “distance”. The following functions have been renamed accordingly:

  • wiz.graph.compute_priority_mapping() → wiz.graph.compute_distance_mapping()
  • wiz.graph.sorted_from_priority() → wiz.graph.updated_by_distance()

The following function has also be renamed for clarity:

  • wiz.graph.extract_conflicted_nodes() → wiz.graph.extract_conflicting_nodes()

The graph division process has been replaced by a function which creates a generator iterator for each graph combination in order to optimize the resolution process.

Migrate to 0.11.0

The wiz.export_bash_wrapper() and wiz.export_csh_wrapper() functions have been removed and replaced by an wiz.export_script() function which simply take a “script_type” argument.

The wiz.export_definition() function arguments have been updated so that only a data mapping is required. The “packages” argument which were used to pass a list of Package instances to indicate the requirements list is no longer necessary as the requirements list could directly be passed to the data mapping. This implies that the user no longer need to fetch the corresponding packages prior to export a definition.

Migrate to 0.9.0

The following functions have been renamed as part of a refactoring of the high-level API:

The wiz.fetch_definition() function has been modified to only return the definition instance from a package definition request.

The wiz.discover_context() function does not need any definition mapping argument as it will be fetched internally.

The wiz.resolve_command_context() function has been removed. The command should be resolved independently and the context should be discovered from the corresponding package request.