stormlibpp.stormpkg module

Python objects for working with Storm Packages.

class stormlibpp.stormpkg.StormPkg(check_syntax: bool = True, proto_dir: str | None = None)

Bases: object

A Python representation of a Storm package, proto and definition.

This class must be subclassed - this is how default proto dir loading is supported.

By default, the subclasses expect a Storm package proto to be stored in a pkgproto directory that is within the same directory as the __init__.py of the module the object is defined within. This can be changed. But, if it isn’t, this means you must setup your package proto files to be built with your Python module.

By default, subclasses look for a Yaml package proto file with a basename equal to the lowercase version of the subclass’ name. Subclasses must override the proto_name class property to change this behavior.

This object is ready to use on init - access the pkgdef prop for the full Storm package definition loaded from the definied package proto. The pkgdef property is also returned by this object’s asdict method.

It takes the following steps on start up:

  • Resolves the path of the package proto based on proto_name and proto_dir.

  • Loads the package proto using synapse.tools.genpkg.tryLoadPkgProto.

  • Converts the returned object to a dict using json.dumps and json.loads.

    • This is necessary because tryLoadPkgProto returns a “tuplified” object (the return of synapse.common.tuplify). Which can return immutable objects that synapse.cortex.Cortex.addStormPkg expects to be mutable. So a StormSvc._storm_svc_pkgs works best when it is set to a dict.

  • Sets the loaded package definition’s build key to a dict containing the time using synapse.common.now.

  • Stores the package definition dict in the pkdef property.

  • If check_syntax is True, all Storm code that is loaded in the pkdef is passed to Synapse’s Storm parser to check for Storm syntax errors. Any errors are raised as a StormPkgSyntaxError exception.

Examples:

# Just subclass StormPkg with a name that matches the Yaml definition.
class ThePkg(StormPkg):
    '''The Yaml file this class will read must be named ``thepkg.yaml``.'''

# Or declare a subclass with a custom package def name
# (``storm.pkg.yaml``) that is different from the class name.
class SomePkg(StormPkg):
    proto_name = 'some.pkg'

# Use the package in a Storm Service API class declaration
class SomeApi(s_cell.CellApi, s_stormsvc.StormSvc):
    ...
    _storm_svc_pkgs = (SomePkg().asdict(),)

Parameters

check_syntaxbool, optional

Whether to check the syntax of this package’s loaded Storm code. By default True.

proto_dirstr | None, optional

The fully resolved directory that the package proto is in. A value of None tells StormPkg to resolve this path automatically based on the rules defined elsewhere in this docstring. By default None.

Properties

default_namestr

The Yaml basename used if proto_name is empty (not set). Set to the value of self.__class__.__name__.lower().

pkgdefdict

The loaded Storm package definition.

proto_dirstr

The directory that the Storm package’s proto is in. This is the proto_dir argument if it is passed. Otherwise, the dir is resolved by looking at the self.__class__.__module__ name at init, finding the object this resolves to in sys.modules, and reading the module’s __file__. Then joining this file’s dir name with the value pkgproto.

proto_namestr

A class property containing the name of the Storm package’s proto Yaml file (without extension). Subclasses may override this class property to set a custom proto Yaml file basename. If they don’t, this property is automatically set to the value of self.default_name.

Raises

StormPkgBadDefError

If the package proto either has an invalid schema or bad value.

StormPkgNoProtoError

If the proto Yaml file cannot be loaded. This can happen if the file name will not match self.default_name but proto_name is not set.

StormPkgResolveError

If the default package proto dir cannot be resolved. This can be the case if a StormPkg is created and doesn’t expect to use the default proto dir but a custom proto_dir is not passed.

StormPkgSyntaxError

If check_syntax is True and the Storm code in this package has syntax errors.

RuntimeError

If this class is instantiated directly and not subclassed.

asdict()

Return this objects full Storm package definition as a Python dict.

Pointer to self.pkgdef.

check_syntax() None

Check the Storm syntax of this package’s loaded Storm code.

Raises

StormPkgSyntaxError

If the syntax of a any Storm code is invalid. We fail the whole package because one bad Storm file will cause loading failures on the Cortex for all other files too.

property cmdnames: list[str]

The names of the commands this package defines, if any.

cmds() list[dict]

The full definitions of the commands this package defines.

property modnames: list[str]

The names of the modules this package defines, if any.

mods() list[dict]

The full definitions of the modules this package defines.

property pkg_guid: str | None

The package’s guid, None if not set.

property pkg_name: str | None

The package’s name, None if not set.

property pkg_ver: str | None

The package’s version, None if not set.

pkgdef

A Python dict containing the full Storm package definition.

proto_name: str | None = None

The basename of this Storm package’s Yaml proto file.

storm() dict[str, str]

The Storm code this package defines.

Iterates over the dicts from cmds() + mods() to map all names to the Storm code each dict defines in the storm key.

Returns

dict[str, str]

Keys are the module/command name and values are the Storm code.