ways.base.situation module

The most important part of Ways - A module that contains Context objects.

Context objects are persistent objects that are created using a Flyweight pattern. Once one instance of a Context is created, it is reused whenever the same Context is called again - which means it can be used like a monostate.

Reference:

http://sourcemaking.com/design_patterns/flyweight http://sourcemaking.com/design_patterns/flyweight/python/1

The Python example is written in Python 3 but is the same idea.

Parts of the Context are generated at runtime and cannot be directly modified (like, for example, its Plugin objects). Other parts are dynamic (like the Context.data property).

class ways.base.situation.Context(hierarchy, assignment='', connection=None)

Bases: object

A collection of plugins that are read in order to resolve its methods.

as_dict(changes=True)

Convert this object into a dictionary.

This is different from a standard repr(Context) because it will include items that are not part of the Context’s initialization.

It also creates a deepcopy of its contents, so that any changes to this dictionary won’t affect the original object.

Parameters:changes (bool, optional) – If True, the output will contain original plugin data as well as any changes that the user made over top of the original. If False, only the original information is returned. Default is True. Returns:A copy of the current information of this class. Return type:dict[str]

checkout(assignment='master')

Make a new Context instance and return it, with the same hierarchy.

Parameters:assignment (str, optional) – The new assignment to get. Returns:The new Context object. Return type:ways.api.Context

data

dict[str] – Data that was automatically generated and user data.

get_action(name)

ways.api.Action or callable or NoneType: The Action.

get_all_plugins(hierarchy='', assignment='')

list[ways.api.Plugin]: The found plugins, if any.

get_all_tokens()

Get the tokens in this Context’s mapping and any subtokens.

Subtokens are tokens that are inside another token’s mapping.

Returns:All of the tokens known to this Context. Return type:set[str]

get_assignment()

str: The assignment for this Context.

get_groups()

tuple[str]: The groups that this Context belongs to.

get_hierarchy()

tuple[str]: The path to this Context.

get_mapping()

str: The mapping that describes this Context.

get_mapping_details()

Get the information that describes a Context instance’s mapping.

This function is the same as “mapping_details” key that you’d see in a Plugin Sheet file and is critical to how a Context’s parser builds into a file path.

Without it, you cannot get a proper filepath out of a Context.

Returns:The information. Return type:dict[str]

get_mapping_tokens(mapping='')

list[str]: Get all of the tokens that are in this Context’s mapping.

get_max_folder()

str: The highest mapping point that this Context lives in.

get_parser()

ways.api.ContextParser: A parser copy that points to this Context.

get_platforms()

Get The OSes that this Context runs on.

The recognized platforms for this method is anything that platform.system() would return. (Examples: [‘darwin’, ‘java’, ‘linux’, ‘windows’]).

Returns:The platforms that this Context is allowed to run on. Return type:set[str]

get_str(*args, **kwargs)

Get the Context’s mapping as filled-out text.

Parameters:

• *args (list) – Positional args to send to ways.api.ContextParser.get_str.
• **kwargs (dict) – Keyword args to send to ways.api.ContextParser.get_str.

is_path()

bool: If the user indicated that the given mapping is a filepath.

plugins

Find all of the “valid” plugins for this instance.

What decides if a Plugin is “found” depends on a number of factors. First, the plugin needs to be inside the hierarchy of the Context, have the same assignment, and the platform(s) assigned to the Plugin must match our current system’s platform. If a platform override is specified (aka if WAYS_PLATFORM has been set) then the Plugin object’s platform has to match that, instead.

Raises:

• ValueError – If the platform in WAYS_PLATFORM was invalid.
• ValueError – If the plugin found has a platform that is not found in our recognized_platforms variable.

Returns:

The found plugins.

Return type:

list[ways.api.Plugin]

revert()

Set the data on this instance back to its default.

classmethod validate_plugin(plugin)

Check if a plugin is “valid” for this Context.

Typically, a plugin is invalid if it was meant for a different OS (example), a Windows plugin shouldn’t be added to a Context that is being run on a Linux machine.

Parameters:

plugin (ways.api.Plugin) – The plugin to check.

Raises:

• OSError – If the user specified an unrecognized environment using the PLATFORM_ENV_VAR environment variable.
• EnvironmentError – If the plugin’s environment does not match this environment.

Returns:

The plugin (completely unmodified).

Return type:

ways.api.Plugin

ways.base.situation.clear_aliases()

Remove all the stored aliases in this instance.

ways.base.situation.clear_contexts()

Remove every Context instance that this object knows about.

If a Context is re-queried after this method is run, a new instance for the Context will be created and returned.

Running this method is not recommended because it messes with the internals of Ways.

ways.base.situation.get_all_contexts()

Get or Create every Context instance that has plugins.

Warning

This method can potentially be slow if there are a lot of Context objects left to be defined. That said, the second time this method is called, it’ll be fast because the Context instances will be retrieved from the Context flyweight cache.

Returns:Every Context object found by Ways. Return type:list[ways.api.Context]

ways.base.situation.get_context(hierarchy, assignment='', follow_alias=False, force=False, *args, **kwargs)

Get a persistent Context at some hierarchy/assignment location.

This function uses a Flyweight factory to manage the instance objects that it returns.

Reference:

http://sourcemaking.com/design_patterns/flyweight http://sourcemaking.com/design_patterns/flyweight/python/1

Parameters:

• hierarchy (tuple[str]) – The location to look for our instance.
• assignment (str) – The category/grouping of the instance. If no assignment is given, Ways will gather plugins in the order defined in the WAYS_PRIORITY environment variable and create plugins based on that.
• *args (list) – If an object instance is found at the hierarchy/assignment, this gets passed to the instantiation of that object.
• **kwargs (dict[str]) – If an object instance is found at the hierarchy/assignment, this gets passed to the instantiation of that object.

Returns:

An instance of that class. If the Context that is queried doesn’t have any Plugin objects defined for it, it’s considered ‘empty’. To avoid faults in our code, we return None.

Return type:

<class_tuple instance> or NoneType

ways.base.situation.get_current_platform()

Get the user-defined platform for Ways.

If WAYS_PLATFORM is not defined, the user’s system OS is returned instead.

Returns:The platform. Return type:str

ways.base.situation.register_context_alias(alias_hierarchy, old_hierarchy)

Set a hierarchy to track the changes of another hierarchy.

This function lets you refer to plugins and Context objects without specifying their full names.

Example

>>> class SomePlugin(plugin.Plugin):
>>>     def get_mapping(self):
>>>         return '/some/path/here'

>>>     def get_hierarchy(self):
>>>         return ('nuke', 'scenes')

>>>     def get_platforms(self):
>>>         return '*'

>>> class AnotherPlugin(plugin.Plugin):
>>>     def get_mapping(self):
>>>         return '/some/path/here'

>>>     def get_hierarchy(self):
>>>         return ('maya', 'scenes')

>>>     def get_platforms(self):
>>>         return '*'

>>> sit.register_context_alias('maya_scenes', 'maya/scenes')
>>> context = ways.api.get_context('maya_scenes')
>>> # The resulting Context object has the hierarchy ('maya_scenes', )
>>> # but has all of the plugins from 'maya/scenes'

>>> sit.register_context_alias('maya_scenes', 'nuke/scenes')

>>> # Now, the Context('maya_scenes') is pointing to a Nuke Context
>>> # we can immediately work with this Context without having to
>>> # re-instantiate the Context

Raises:ValueError – If the alias is the same as the hierarchy that it’s trying to be aliased to or if the alias was already defined.

ways.base.situation.resolve_alias(hierarchy)

Get the real hierarchy that the given alias represents.

Parameters:hierarchy (iter[str] or str) – The alias hierarchy to convert. Returns:The real hierarchy. Return type:tuple[str]