Decorators

nutcli.decorators.Identity(function)

Identity decorator. It does nothing to the decorated function.

It can be used to simplify the code.

Example usage

def identity_example(ignore_errors):
    decorator = IgnoreErrors if ignore_errors else Identity

    @decorator
    def do_something():
        pass

nutcli.decorators.IgnoreErrors(function)

All exceptions raised from the decorated function will be ignored.

Example usage

@IgnoreErrors
def raise_error(ignore_errors):
    raise Exception('This will be ignored.')

raise_error()

class nutcli.decorators.Timeout(timeout=None, message=None)

Bases: object

A nutcli.exceptions.TimeoutError is risen if the decoration function does not finish in time.

The code is based on timeout-decorator: - https://github.com/pnpnpn/timeout-decorator

Example usage

@Timeout(2)
def be_slow():
    time.sleep(5)

try:
    be_slow()
except nutcli.exceptions.TimeoutError as e:
    print(str(e))

Parameters

• timeout (int, str, optional) – Timeout in seconds or a simple time format, defaults to None.

• message (str, optional) – Error message, defaults to None

Parameter timeout may contains one of the following values:

• None: No timeout is applied

• int: Number of seconds

• 'X seconds Y minutes Z hours': Simple natural time specifications

  • X, Y and Z can be float

  • Each of seconds, minutes and hours can be omitted

  • Suffix s can be omitted

Parameter message is passed to nutcli.exceptions.TimeoutError constructor.

class nutcli.decorators.LogExecution(message=None, printer=None, logger=None)

Bases: object

If enabled, each call of decorated method will produce an info log message.

Example usage

@LogExecution()
def example():
    pass

LogExecution.enabled(True)

example()
# -> INFO example()

Parameters

• message (str, optional) – Message to log, defaults to None

• printer (nutcli.utils.LogExecutionPrinter, optional) – Execution printer, defaults to None

• logger (logger, optional) – Logger, defaults to None (= nutcli.message)

If printer is None then nutcli.utils.LogExecutionPrinter is used. The printer will log the message using logger.

The default printer will either produce message if it is not None or exact function call.

classmethod enabled(enabled=True)

Enable or disable execution logging.

Parameters

enabled (bool, optional) – The state, defaults to True

class nutcli.decorators.SideEffect(message=None, returns=None, printer=None, logger=None)

Bases: nutcli.decorators.LogExecution

If dry run is enabled the decorated function will not be run and only its execution is printed to the info log. The dry run can be enabled with dry_run().

Note

Since this inherits from LogExecution it will also produce a log execution message if it is enabled.

Example usage

@SideEffect()
def example():
    # remove files
    pass

SideEffect.dry_run(True)

example()
# -> INFO example()
# Files are not deleted, example() is not executed.

Parameters

• message (str, optional) – Message to log, defaults to None

• returns (any, optional) – Return value of the decorated function if dry run is enabled, defaults to None

• printer (nutcli.utils.LogExecutionPrinter, optional) – Execution printer, defaults to LogExecutionPrinter()

• logger (logger, optional) – Logger, defaults to None (= nutcli.message)

If printer is None then nutcli.utils.LogExecutionPrinter is used. The printer will log the message using logger.

The default printer will either produce message if it is not None or exact function call.

Call to the decorated function will return returns if dry run is enabled.

classmethod dry_run(enabled=True)

Enable or disable dry run.

Parameters

enabled (bool, optional) – The state, defaults to True