fabsetup.utils

Fabsetup utils.

fabsetup.utils.colors

Wrap text with ANSI escape color sequences.

Code originally comes from Fabric-1, default_color and no_color were added.

Examples:

.>> print(blue('foo'))
\033[34mfoo\033[0m

.>> print(red('bar', bold=True))
\033[1;31mbar\033[0m

.>> print(no_color('baz'))
baz

Color codes:

black:   30
red:     31
green:   32
yellow:  33
blue:    34
magenta: 35
cyan:    36
white:   37

default_color: 0

fabsetup.utils.colors.black(text, bold=False)

fabsetup.utils.colors.red(text, bold=False)

fabsetup.utils.colors.green(text, bold=False)

fabsetup.utils.colors.yellow(text, bold=False)

fabsetup.utils.colors.blue(text, bold=False)

fabsetup.utils.colors.magenta(text, bold=False)

fabsetup.utils.colors.cyan(text, bold=False)

fabsetup.utils.colors.white(text, bold=False)

fabsetup.utils.colors.default_color(text, bold=False)

fabsetup.utils.colors.no_color(text, bold=False)

By default, return text unchanged.

If bold is True, return wrapped using default color code in bold style.

fabsetup.utils.colors.color_by_name(name)

fabsetup.utils.colors.config_color(config, path, default)

fabsetup.utils.decorate

Function decorator helper.

fabsetup.utils.decorate.invoked(args, kwargs)

Return True if args is None or if kwargs is not None.

This means if a decorator which calls invoked() decorates a function invoked, i.e. with braces containing zero or more kwargs, invoked() returns True. And returns False, if the decorator decorates a function non-invoked, i.e. without braces.

Examples:

>>> import json  # print dict `kwargs` in order

>>> def decorator(*args, **kwargs):
...
...     def inner(func):
...         print('inner')
...         return func
...
...     if invoked(args, kwargs):
...         print('invoked',
...               args,
...               json.dumps(kwargs, sort_keys=True))
...         return inner
...
...     print('not invoked')
...     return inner(func=args[0])

>>> # non-invoked decorator
>>>
>>> @decorator
... def foo():
...     pass
not invoked
inner

>>> # "manually" apply non-invoked decorator
>>>
>>> def foo():
...     pass
...
>>> foo = decorator(foo)
not invoked
inner

>>> # invoke decorator without kwargs
>>>
>>> @decorator()
... def foo():
...     pass
invoked () {}
inner

>>> # invoke decorator with kwargs
>>>
>>> @decorator(a=1, b=2)
... def foo():
...     pass
invoked () {"a": 1, "b": 2}
inner

>>> # "manually" apply decorator with kwargs
>>>
>>> def foo(args, kwargs):
...     pass
...
>>> tmp = decorator(0, a=1, b=2)
invoked (0,) {"a": 1, "b": 2}
>>> foo = tmp(foo)
inner

>>> # invoke decorator with args but without kwargs
>>> # (not possible)
>>>
>>> @decorator(0, 1, 2)
... def foo():
...     pass
Traceback (most recent call last):
    ...
TypeError: 'int' object is not callable

fabsetup.utils.decorators

Function decorators.

fabsetup.utils.decorators.print_doc(*args, **kwargs)

Print the docstring of the decorated function.

May be invoked as a simple, argument-less decorator (i.e. print_doc) or with named arguments color, bold, prefix, or tail (eg. print_doc(color=utils.red, bold=True, prefix=' ')).

Parameters:

• color – Optionally define another color, default is color is utils.colors.blue.

• bold (bool) – Optionally print docstring in bold letters, default is False.

• prefix (str) – Optionally set a prefix, default is ‘’ (empty string).

• tail (str) – Optionally set a tail, default is ‘n’.

Examples:

>>> # a context/connection is required
>>> import invoke.context
>>> c = invoke.context.Context()

>>> # argument-less
>>> @print_doc
... def func(c):
...     """docstring of func"""
...     pass
>>>
>>> func(c)
docstring of func


>>> # with named arguments
>>> @print_doc(color=no_color, tail='\n\nNote! foobar')
... def func(c):
...     """docstring of func"""
...     pass
>>>
>>> func(c)
docstring of func

Note! foobar

fabsetup.utils.decorators.print_full_name(*args, **kwargs)

Print the full name of the decorated function.

May be invoked as a simple, argument-less decorator (i.e. print_full_name) or with named arguments color, bold, prefix, or tail (eg. print_full_name(color=utils.red, bold=True, prefix='')).

Parameters:

• color – Optionally define another color, default is color is no_color.

• bold (bool) – Optionally print docstring in bold letters, default is False.

• prefix (str) – Optionally set a prefix, default is ‘’ (empty string).

• tail (str) – Optionally set a tail, default is ‘\n’.

• name (str) – Optionally set for another function name.

• numbered ([int]) – Optionally set a numeration identifier

Examples:

>>> # a context/connection is required
>>> import invoke.context
>>> c = invoke.context.Context()

>>> # argument-less
>>> @print_full_name
... def func(c):
...     pass
>>>
>>> func(c)
func

>>> # with named arguments
>>> @print_full_name(color=red, prefix='# ', tail=' mytail')
... def func(c):
...     pass
>>>
>>> func(c)
# func mytail

fabsetup.utils.docstring

Manipulate docstring.

fabsetup.utils.docstring.lstripped_lines(text)

Return multiline string text each line stripped by four spaces if they exist.

Example:

>>> s = '# task\n\n    docstring\n     some'
>>> print(s)
# task

    docstring
     some
>>> t = lstripped_lines(s)
>>> t
'# task\n\ndocstring\n some'
>>> print(t)
# task

docstring
 some

fabsetup.utils.outfile

While preserving output handles write stdout and stderr to outfile.

class fabsetup.utils.outfile.stream_tee(stream1, stream2, **kwargs)

Bases: object

Tee stream1 to stream2.

Basically, stream_tee returns a wrapper of stream1 which hooks in every method call for a method of stream1 to be called on stream2, too.

Parameters:

• stream1 (TextIO) – First filehandle.

• stream2 (TextIO) – Second filehandle.

• stream1_color (fabsetup.utils.colors.color-function) – Optionally set a color for stream1.

• stream2_line_prefix (str) – Optionally set line prefix for stream2 which will be prepended to each line written.

• stream2_no_prefix_lines (list<str>) – Optionally define lines which woud not prepended by a prefix when written.

Returns:

stream1 wrapper which applies the tee feature.

Examples:

>>> # Prepare
>>> import sys
>>> import tempfile
>>> stdout_orig = sys.stdout

>>> # First Example
>>> outfile_handle = tempfile.TemporaryFile()
>>> sys.stdout = stream_tee(sys.stdout, outfile_handle)
>>> # output would be written to stdout and outfile

>>> # Reset
>>> sys.stdout = stdout_orig

>>> # Second Example
>>> sys.stdout = stream_tee(sys.stdout, sys.stdout)
>>> print("out")
outout

class fabsetup.utils.outfile.Singleton(name, bases, dict)

Bases: type

Singleton metaclass.

class fabsetup.utils.outfile.Tee(*args, **kwargs)

Bases: object

Single instance class in order to write both, stdout and stderr into a file and also to keep stdout and stderr output active.

Uses fabsetup.outfile.Singleton as metaclass.

set_outfile(filename, prefix='')

Define the outfile where stdout and stderr will be written to.

Recursively create parent dirs of filename if they not exist.

If the outfile already exists it will be overwritten.

Parameters:

• filename (str) –

• prefix (str) – Optionally write prefix to outfile at first.

start()

Set up stdout, stderr and outfile handles and if given write prefix to outfile.

Uses fabsetup.utils.outfile.stream_tee().

stop()

Reset stdout and stderr to previous handles and close outfile handle.

pause()

Alias for stop()

resume(missed_output='')

Set up like in start() but append to outfile.

Optionally write missed_output to outfile.

Parameters:

missed_output (str) –

fabsetup.utils.outfile.remove_color_codes(filename)

Remove ANSI color codes from a file inplace.

Parameters:

filename (str) –

fabsetup.utils.pandoc

With a locally installed Pandoc add a table of content (toc) to Markdown files and create HTML from Markdown files.

class fabsetup.utils.pandoc.Pandoc(command='/usr/bin/pandoc')

Bases: object

Pandoc command execution interface.

Parameters:

command (str) – Optionally, path to Pandoc executable.

command_available()

Check if pandoc command is available.

Return True if command is available, else False.

add_toc(filename)

Add a table of content to a Markdown file (inplace).

Parameters:

filename (str) – Name of the Markdown file.

Returns:

True if toc has been added, else False.

create_html(filename_from, filename_to, css_url='', inline=False)

From a Markdown file create an HTML file.

Recursively create parent dirs of filename_to if they not exist.

Parameters:

• filename_from (str) – Name of the Markdown file.

• filename_to (str) – Name of the HTML file.

• css_url (str) – Optional, URL of a CSS file.

• inline (bool) – Optionally embed CSS inline into the HTML file.

Returns:

True if HTML file has been created, else False.