API Summary

The API Summary is a brief description of the major parts of Ways.

Ways is an API that helps developers define and use Context and Asset objects. Contexts and Assets aren’t directly created. Instead, they’re generated by Ways, automatically, from plugins defined in a Plugin Sheet.

Your job as the user is to define plugins. Those plugins will describe Contexts. If needed, Contexts and Plugins can be defined and registered manually but this isn’t the default behavior of Ways.

Plugin Sheets

Plugins Sheets are files on disk or on a server that describe a Context. Once a single plugin in a single Plugin Sheet is created, it can be immediately used. Adding more plugins will append to the existing Context or create more Contexts.

Plugin Sheets can be JSON, YAML, or Python files.

Descriptor Objects

A Descriptor is a class or function used to load Plugin Sheets. Whenever a file or folder path is added to WAYS_DESCRIPTORS, Ways generates Descriptor objects in the background.

For most people, just knowing that Descriptors exist is all they’ll need to know.

That said, the Descriptor objects that ship with Ways only cover filepaths and local/remote git repositories. If you need something special, check out Descriptors to learn how Descriptors work to create your own.

Plugins

Descriptor objects determine how Plugin Sheets load. The ones that Ways ship with recognize JSON, YAML, and Python files in alphabetical order but it can be changed to whatever you want by creating and using your own Descriptor objects.

Whenever a user tries to create a Context, the Context’s Plugin objects are looked up as read-only data, combined, and then hooked into the Context.

Context Objects

Context objects are containers of metadata and Plugin information.

Plugins are loaded into a Context on-demand - A Plugin Sheet can be defined, and afterwards a Context object could be instantiated, and then more Plugin Sheets / Descriptors could be added in a single interactive session and the original Context you created will already have all the new Plugin settings.

(It’s not recommended to do this but Ways will allow it).

There’s a ton of things that you can use Context objects to do but to keep this page short, the examples will stop here. Go to Getting Started to try it for yourself if you’re ready.

Asset Objects

Once you’ve worked with them for a short while, it’ll become obvious that Context objects are pretty limited. Also, every hierarchy is only ever allowed one instance of a Context which further limits how useful they can be.

An Asset object is basically the same as a Context object but you can instantiate new version of them any time you’d like. Also, Asset objects contain extra information about the Context. The Asset object is a very minimal implementation of an Asset Management System (AMS) and is heavily relies on Actions and its Context to do the heavy-lifting.

Action Objects

Actions are classes or functions that attach to a Context or Asset. Actions can be defined ahead of the Context/Asset objects that they act upon and do completely different things for different hierarchies.

Head over to getting_started to learn about creating Descriptors, Contexts, Actions, and more.