API Reference

Jobs

BaseJob and BaseJobSchema for building out a Spacewalk job processing service

class spacewalk.jobs.BaseJobSchema(*, only: Optional[Union[Sequence[str], Set[str]]] = None, exclude: Union[Sequence[str], Set[str]] = (), many: bool = False, context: Optional[Dict] = None, load_only: Union[Sequence[str], Set[str]] = (), dump_only: Union[Sequence[str], Set[str]] = (), partial: Union[bool, Sequence[str], Set[str]] = False, unknown: Optional[str] = None): Bases: zerog.jobs.base.BaseJobSchema

class spacewalk.jobs.BaseJob(*args, **kwargs)

Bases: zerog.jobs.base.BaseJob

The base class for all Spacewalk jobs.

Variables

NAME (str) – Human friendly job or branch name which will be shown for the /branches or /leaves endpoint. You MUST override this attribute for all jobs.
BRANCH_NAME (str) – Name by which a branch is identified in endpoints. You MUST override this attribute for a branch (parent) job
LEAF_NAME (str) – Name by which a leaf is identified in endpoints. You MUST override this attribute for a leaf (endpoint) job
DESCRIPTION (str) – Human friendly string describing the job in more detail. This description will be shown in the /branches or /leaves endpoint. You MUST override this attribute for all jobs.
BASE_SCHEMA (class) – The marshmallow schema used to serialize/deserialize this job. You MAY override this attribute to add fields to the base schema. The schema MUST be a subclass of BaseJobSchema.
Params (class) – The marshmallow schema used to define this job’s input parameters for an HTTP POST to the /job endpoint, which creates a job. You MAY override this attribute to define your job’s inputs. The /post-schema endpoint will document these input Params as a JSON-Schema. The Params class definition can be nested in the job class as shown here, or defined outside the job class and assigned as a class attribute.

Subclasses MUST

override the run() method

BASE_SCHEMA: alias of spacewalk.jobs.BaseJobSchema

class Params(*, only: Optional[Union[Sequence[str], Set[str]]] = None, exclude: Union[Sequence[str], Set[str]] = (), many: bool = False, context: Optional[Dict] = None, load_only: Union[Sequence[str], Set[str]] = (), dump_only: Union[Sequence[str], Set[str]] = (), partial: Union[bool, Sequence[str], Set[str]] = False, unknown: Optional[str] = None): Bases: marshmallow.schema.Schema

__init__(*args, **kwargs)

Initialize the job with deserialized data.

Subclasses MUST override this method if they use a subclass of BaseJobSchema to add fields.

If overriding this method, you MUST call the parent __init__() using super

This __init__() method is the opportunity to load any extra fields that are declared in the associated schema.

Required fields can be loaded directly by referencing their key.

Optional fields need to be loaded using the dictionary’s get method, which gives an opportunity to load the field with a default value if it isn’t present in the input data.

Example:

def __init__(self, *args, **kwargs):
    super().__init__(*args, **kwargs)

    self.requiredField = kwargs['requiredField']
    self.optionalField = kwargs.get('optionalField', "default")

Server

Spacewalk Server class definition

class spacewalk.server.Server(structure, *args, **kwargs)

Bases: zerog.server.Server

Base Spacewalk server class

__init__(structure, *args, **kwargs)

Parameters

structure (spacewalk.Structure) – object that defines the tree and pathmap for an auto-generated spacewalk REST API
*args – positional arguments passed through to the zerog.Server parent class
**kwargs – keyword arguments passed through to the zerog.Server parent class

Structure

Spacewalk tools for auto-generating a REST API structure

exception spacewalk.structure.NotLeafError: Bases: Exception

class spacewalk.structure.Branch(cls, branches, leaves, path)

Bases: object

A branch node in a Spacewalk tree. Saves the associated job class, REST path, and any branches or leaves that are below it.

A full Spacewalk tree is referenced by its root Branch.

A Branch job serves as a parent class for the Branches & Leaves below it in the tree. It doesn’t get run.

__init__(cls, branches, leaves, path)

Parameters

cls (spacewalk.BaseJob subclass) – job class for this node
branches (list of spacewalk.BaseJob subclasses) – Branch nodes that are beneath this Branch
leaves (list of spacewalk.BaseJob subclasses) – Leaf nodes that are beneath this Branch
path (str) – path portion of the Branch’s URI

class spacewalk.structure.Leaf(cls, path)

Bases: object

An end node in a Spacewalk tree. Saves the associated job class, REST path, and the json schema for the job’s parameters.

Leaf jobs are the jobs that actually run.

__init__(cls, path)

Parameters

cls (spacewalk.BaseJob subclass) – job class for this node
path (str) – path portion of the Leaf’s URI

spacewalk.structure.auto_tree(rootcls, path)

Automatically build a Spacewalk tree by recursively walking through the subclasses of a root class.

Parameters

rootcls (spacewalk.BaseJob subclass) – the root job class. The Spacewalk tree is built by walking through the subclasses of the root.
path (str) – root path for all the URIs in this tree

Returns tree

the Branch at the tree’s root

spacewalk.structure.make_path_map(rootbranch, pathmap)

Recursively build a dictionary that maps all the endpoints in a tree to their associated Branches or Leaves

Parameters

rootbranch (Branch) – the tree’s root Branch
pathmap (dict) – base pathmap to add to

Returns pathmap

class spacewalk.structure.Structure(tree)

Bases: object

Spacewalk structure class which contains a tree and a pathmap, and methods to extract useful things from the structure.

__init__(tree)

Parameters: tree (Branch) – root of Spacewalk tree

get_root_path()

Returns path: root path for this structure
Return type: str

get_branch_paths()

Returns paths: list of paths to branches
Return type: list of str

get_leaf_paths()

Returns paths: list of paths to leaves
Return type: list of str

get_sub_branches(path)

Return all the sub branches associated with a path.

Parameters: path (str) – base path
Returns sub branches: list of dictionaries for each sub branch. Dictionary keys are ‘path’, ‘name’, ‘description’
Raises: KeyError – if there is no branch for the path

get_leaves(path)

Return all the leaves associated with a path.

Parameters: path (str) – base path
Returns leaves: list of dictionaries for each leaf Dictionary keys are ‘path’, ‘name’, ‘description’
Raises: KeyError – if there is no branch for the path

get_post_schema(path)

get the json-schema for a POST to a leaf

Parameters: path (str) – path portion of the leaf’s URI
Returns schema
Return type: json-schema dictionary
Raises: NotLeafError – if path is not for a leaf

get_job_type(path)

get the job type for a leaf.

Parameters: path (str) – path portion of the leaf’s URI
Returns jobType
Return type: str
Raises: NotLeafError – if path is not for a leaf

Handlers

Request handlers and endpoints for the auto-generated Spacewalk API

class spacewalk.handlers.BranchHandler(*args, **kwargs)

Bases: zerog.handlers.base.BaseHandler

Returns a list of sub-branches or leaves for a branch. Must be subclassed and subclass must override the get_collection method

class spacewalk.handlers.SubBranchesHandler(*args, **kwargs)

Bases: spacewalk.handlers.BranchHandler

Returns a list of info dictionaries for each sub-branch of a branch

class spacewalk.handlers.LeavesHandler(*args, **kwargs)

Bases: spacewalk.handlers.BranchHandler

Returns a list of info dictionaries for each leaf in a branch

class spacewalk.handlers.PostSchemaHandler(*args, **kwargs)

Bases: zerog.handlers.base.BaseHandler

Returns a JSONSchema of the parameters to pass for a POST to a leaf endpoint

class spacewalk.handlers.RunJobHandler(*args, **kwargs)

Bases: zerog.handlers.run_job.RunJobHandler

Starts a zerog job for a particular endpoint.

Arguments are validated by attempting to create the job.

derive_job_type(data, *args, **kwargs)

Extract jobType from the POST. Handles several different options:

named keyword argument extracted from the URL

positional argument extracted from the URL

field in a json-encoded request body

Override this method to custom-synthesize jobType from the request

spacewalk.handlers.make_handlers(structure): makes a list of endpoint -> request handler tuples for use by the Spacewalk Tornado server