ways.base.descriptor module

A module that holds classes which abstract how Plugin objects are created.

A descriptor string could be a path to a file or folder or even to a database

class ways.base.descriptor.FileDescriptor(items)

Bases: object

A generic class that creates Plugin objects from a file, on-disk.

Note

Any FileDescriptor class that returns back Plugin objects is valid (Descriptors can query from a database, locally on file, etc, etc. It’s all good) except there is one major requirement. FileDescriptor-like objects cannot append asynchronously. In other words, If a FileDescriptor manages threads that each find Plugin objects and append to a list of Plugin objects whenever each thread finishes, the Plugin objects might append out of order - which will create results that will be hard to debug.

It’s recommended to not use threading at all unless this return process is managed (like with a queue or some other kind of idea).

classmethod filter_plugin_files(items)

Only get back the files that are likely to be plugin files.

get_plugin_info(path)

Given some file path, get its metadata info.

Parameters:path (str) – The path to some directory containing plugin objects. Returns:The information about this plugin path. Return type:dict[str]

get_plugins(items=None)

Get the Plugin objects that this instance is able to find.

Note

This object will sort the items it is given before retrieving its Plugin objects so files/folders that are given different priorities depending on how their paths are named.

Parameters:items (iterable[str] or str) – The paths that this FileDescriptor looks for to find Plugin objects. If not items are given, the instance’s stored items are used, instead. Returns:The plugins. Return type:list[ways.api.Plugin]

classmethod get_supported_extensions()

list[str]: The Plugin file extensions.

class ways.base.descriptor.FolderDescriptor(items)

Bases: ways.base.descriptor.FileDescriptor

A generic abstraction that helps find Plugin objects for our code.

Note

Any FileDescriptor class that returns back Plugin objects is valid (Descriptors can query from a database, locally on file, etc, etc. It’s all good) except there is one major requirement. FileDescriptor-like objects cannot append asynchronously. In other words, If a FileDescriptor manages threads that each find Plugin objects and append to a list of Plugin objects whenever each thread finishes, the Plugin objects might append out of order - which will create results that will be hard to debug.

It’s recommended to not use threading at all unless this return process is managed (like with a queue or some other kind of idea).

class ways.base.descriptor.GitLocalDescriptor(path, items, branch='master')

Bases: ways.base.descriptor.FolderDescriptor

An object to describe a local git repository.

This class conforms its input to files that its base class can read and then calls it. Otherwise that, it’s not special.

class ways.base.descriptor.GitRemoteDescriptor(url, items, path='', branch='master')

Bases: ways.base.descriptor.GitLocalDescriptor

A Descriptor that clones an online Git repository.

ways.base.descriptor.find_loader(path)

Get the callable method needed to parse this file.

Parameters:path (str) – The path to get the loader of. Returns:

A method that is used to load a Python file object

for the given path.

Return type:callable[file]

ways.base.descriptor.is_invalid_plugin(hierarchy, info)

Detect if a plugin’s hierarchy is invalid, given its loaded information.

A plugin that has cyclic dependencies is considered “invalid”.

Example

>>> cat plugin.yml
... plugins:
...     relative_plugin1:
...         hierarchy: mocap
...         mapping: '{root}/scenes/mocap'
...         uses:
...             - mocap

In the above example, that plugin refers to itself and could cause runtime errors.

Parameters:

• hierarchy (str) – Some hierarchy to check.
• info (dict[str]) – The loaded information of some plugin from a Plugin Sheet file.

Returns:

If the plugin is valid.

ways.base.descriptor.try_load(path, default=None)

Try our best to load the given file, using a number of different methods.

The path is assumed to be a file that is serialized, like JSON or YAML.

Parameters:

• path (str) – The absolute path to some file with serialized data.
• default (dict, optional) – The information to return back if no data could be found. Default is an empty dict.

Returns:

The information stored on this object.

Return type:

dict