Class Reference

class pylease.Pylease(parser, cmd_subparsers, info_container)

The main class of Pylease, which contains all the needed resources for extensions. This class is initialised once and by Pylease, which is the so called lizy object. It is passed to Command and Extension instances.

info_container

pylease.InfoContainer

Contains information about current status of the project. Minimal information is name and version.

commands

dict

A dictionary of Pylease commands, including commands defined in extensions if any. The values of the dictionary are instances of Command class.

parser

argparse.ArgumentParser

The root parser of Pylease. Use this object to add command line arguments to Pylease on the same level as --version and --help.

config

dict

A dictionary representing the configuration parsed from setup.cfg defined under [pylease] section. If a configuration value in the configuration file is defined as key1 = valA, valB, valC then the value of the key1 key of this attribute will be an instance of list and be equal to ['valA', 'valB, 'valC'].

class pylease.InfoContainer

A simple container that maps a provided dictionary to its attributes. This provides the current status of the project, and the minimal built-in information attributes are the following:

name

str

The name of the project.

version

str

The current versin of the project

is_empty

bool

The status of current working directory, i.e. indicates whether it is empty or not.

set_info(**kwargs)

Used to extend the information about the project.

Example

Below are two options on how to use/extend the InfoContainer:

info = InfoContainer()

# Option 1
info.set_info(info1='value2', info2='value2')

# Option 2
more_info = {'info3': 'value3'}
info.set_info(**more_info)

# Then you can access your info as instance attributes
print(info.info2)  # will print 'value2'
class pylease.ext.Extension(lizy)

The entry point to implementing Pylease extensions. Pylease loads subclasses of this class and invokes the load() method.

_lizy

pylease.Pylease

The Pylease singleton, that is initialised and passed to all subclass instances.

load()

This method is being called by Pylease when all the extensions are being loaded. All the initialisation code must be implemented in the body of this method.

class pylease.cmd.task.BeforeTask(rollback=None)
execute(lizy, args)

The place where the extension logic goes on.

Parameters:
  • lizy (pylease.Pylease) – The Pylease singleton that provides all the needed information about the project.
  • args (argparse.Namespace) – The arguments supplied to the command line.
enable_rollback(rollback=None)

Enables a rollback for the task. The provided rollback gets executed in case of failure in the execution stack.

rollback

pylease.cmd.rollback.Rollback

The rollback instance for the task.

class pylease.cmd.task.AfterTask(rollback=None)
execute(lizy, args)

The place where the extension logic goes on.

Parameters:
  • lizy (pylease.Pylease) – The Pylease singleton that provides all the needed information about the project.
  • args (argparse.Namespace) – The arguments supplied to the command line.
_command_result

A dictionary containing information by the completion of the command execution.

class pylease.cmd.Command(lizy, name, description, rollback=None, requires_project=True)

This class is one of the main point of Pylease. For adding new commands just inherit from this class and implement _process_command() method.

__init__(lizy, name, description, rollback=None, requires_project=True)

This constructor should be called from child classes and at least be supplied with at least name and description.

Parameters:
  • lizy (pylease.Pylease) – The lizy object, which is initialized and passed by Pylease.
  • name (str) – The name of the command, which will appear in the usage output.
  • description (str) – Description of the command which will also appear in the help message.
  • rollback (pylease.cmd.rollback.Rollback) – The rollback object that will be executed in case of failure during or after the command. This parameter may be emitted if the command does not need a rollback, or may be set in the process of command execution using the enable_rollback() method, if it depends on some parameters during runtime.
  • requires_project (bool) – Boolean indicating whether the command requires to operate on an existing project. E.g. the init command requires an empty directory.
_process_command(lizy, args)

The method which should be implemented when inheriting the Command. All the command logic must go into this method.

Parameters:
  • lizy (pylease.Pylease) – The Pylease singleton.
  • args (argparse.Namespace) – The arguments passed to the command line while invoking Pylease.
add_before_task(task)

Adds a BeforeTask to the Command.

Parameters:task (pylease.cmd.task.BeforeTask) – The task to be added.
add_after_task(task)

Adds a AfterTask to the Command.

Parameters:task (pylease.cmd.task.AfterTask) – The task to be added.
class pylease.cmd.NamedCommand(lizy, description, rollback=None, requires_project=True)

Same as the Command class, however this class enables a little taste of convenience. You can define a class having name with a suffix “Command” and it will automatically assign the prefix of the class name as the command name.

__init__(lizy, description, rollback=None, requires_project=True)

Same as __init__() of Command class, except that the name argument is passed automatically.

class pylease.cmd.rollback.Rollback

This class provides a facility to define a staged rollback process. The scenario of using this class is the following:

  1. Inherit Rollback class
  2. Define rollback stages as instance methods
  3. Decorate each rollback method with Stage decorator, by specifying stage name and priority
  4. Enable each stage separately calling enable_stage() method
enable_stage(stage)

Enable particular stage by name.

Parameters:stage (str) – Stage name to enable.
rollback()

Execute all rollback stages ordered by priority.

class pylease.cmd.rollback.Stage(stage, priority=0)

Decorator used in custom Rollback classes for associating each method with a stage, and setting priority.

Parameters:
  • stage (str) – The name of the stage.
  • priority (int) – The order priority of the stage to be rolled back. Defaults to 0.

Example

Here is an example of how to use the Stage decorator in combination with the Rollback base class:

class ExampleRollback(Rollback):
    @Stage('some_stage', 1)
    def some_stage_with_priority_1(self):
        pass  # your some_stage rollback goes here