fabsetup API¶

fabric-2 tasks and utils. Latest sources

fabsetup.version_str()¶: Return versions of fabsetup addons, fabsetup, fabric, paramiko, and invoke.

Submodules¶

fabsetup.addons¶

Functions to load tasks of available fabsetup addons.

load_pip_addons() and load_repo_addons() will be used in fabsetup.__main__.main() to add fabsetup addons to fabsetup.

fabsetup.addons.module_username(package_name)¶

Return a (module-name, user-name) pair derived from a given fabsetup addon package_name.

A fabsetup addon package-name has a name format fabsetup-USERNAME-TASKNAME where USERNAME is a pypi and git{hub,lab,…} user-name and TASKNAME is the name of the (main) task function of the fabsetup addon.

Parameters:: package_name (str) – Package name of the fabsetup addon, e.g. 'fabsetup-theno-termdown'.
Returns:: Two-tuple of (str, str).

Example:

>>> module_username('fabsetup-theno-termdown')
('fabsetup_theno_termdown', 'theno')

fabsetup.addons.load_addon(package_name)¶

Load fabsetup addon package_name and return it as a (module, collection) pair.

Parameters:: package_name (str) – Package name of the fabsetup addon, e.g. 'fabsetup-theno-termdown'.
Returns:: Two-tuple (“fabsetup_USERNAME_TASKNAME”, invoke.Collection).

fabsetup.addons.load_pip_addons()¶

Load all known fabsetup addons which are installed as pypi pip-packages.

The loaded collections are returned as a list and also stored in list attribute fabsetup.addons.PIP_MODULES.

Returns:: list of [invoke.Collection, invoke.Collection, …],

fabsetup.addons.load_repo_addons()¶

Load all fabsetup addons which are stored under ~/.fabsetup-addon-repos as git repositories.

The loaded collections are returned as a list and also stored in fabsetup.addons.REPO_MODULES.

Returns:: list of [invoke.Collection, invoke.Collection, …],

fabsetup.addons.merge_or_add_r(namespace, collection)¶

Recursively add collection as sub-collection to (mutable) namespace.

If namespace already contains a same-named sub-collection, the tasks and sub-namespaces of collection each will be added to the same-named sub-collection, i.e. merged into it.

Parameters:

namespace (invoke.Collection) – Target collection
collection (invoke.Collection) – The collection where tasks and sub-collections will be taken or merged from.

fabsetup.fabfile¶

@subtask
fabsetup.fabfile.versions(c)¶: Show version numbers of all available fabsetup addons, fabsetup, fabric, paramiko, and invoke.

@subtask
fabsetup.fabfile.help(c, cmd)¶: Show help command

@subtask
fabsetup.fabfile.tasks(c, cmd)¶: Show available tasks.

@subtask
fabsetup.fabfile.task_help(c, cmd)¶: Show task help command.

@task
fabsetup.fabfile.info(c)¶: Show fabsetup info.

fabsetup.fabfile.git_name_and_email_or_die()¶

fabsetup.fabfile.show_or_ask(name, value, default=None)¶

fabsetup.fabfile.sanitize(name, value)¶

@subtask

fabsetup.fabfile.gather_from_user_and_task_name(c, username, task_name)¶

Gather username, task name, addon name, full addon name, and addon dir from username and task name.

Query for username and task name if not set already.

@subtask
fabsetup.fabfile.gather_task_infos(c, headline, description, touched_files)¶: Query for headline, description and touched files if not set already.

@subtask
fabsetup.fabfile.create_files(c, addon_dir, username, addon_name, task_name, author, author_email, headline='', description='', touched_files='')¶: Create addon files.

@subtask
fabsetup.fabfile.create_git_repo(c, basedir)¶: Create git repository.

@subtask
fabsetup.fabfile.summary(c, addon_dir, username, task_name)¶: Summarize addon infos

@task

fabsetup.fabfile.new(c, username=None, task_name=None, headline=None, description=None, touched_files=None)¶

Create a new fabsetup addon.

The created addon will reside inside of a created git repository and contains the fabsetup addon boilerplate code. Afterwards, You can start to add code and functionality to Your addon.

This task needs the following infos from You:

user name
task name
headline, description, and touched (and created) files and dirs for the task docstring and the README.md

You can set them by task argument. If You omit any argument You will be asked for when this task runs.

The addon name will be derived from the task name.

This files and dirs will be created:

~/.fabsetup-addon-repos/fabsetup-{user}-{addon}
                        │
                        ├── fabsetup_{user}_{task}
                        │   ├── __init__.py  # task definition
                        │   └── _version.py
                        │
                        ├── README.md
                        │
                        ├── requirements.txt
                        ├── setup.py
                        │
                        ├── .gitignore
                        │
                        └── .git
                            ├── ...
                            ├── config
                            └── ...

fabsetup.main¶

Executable of fabsetup

class fabsetup.main.Defaults¶

Bases: object

Fabsetup defaults.

as_dict()¶: Return this fabsetup.main.Defaults as dict.

as_restructuredtext_items()¶: Print configuration as list items in restructuredtext.

class fabsetup.main.FabsetupConfig(*args, **kwargs)¶

Bases: Config

A fabric.config.Config subclass which is an invoke.config.Config subclass for prefix manipulation.

This enables for fabsetup prefixed config files and FABSETUP_ prefixed environment variables utilising the same mechanics as Fabric.

prefix = 'fabsetup'¶: The prefix used by Fabsetup => fabsetup.yaml, FABSETUP_ENV_VAR, ...

as_dict()¶

Return this fabsetup.main.FabsetupConfig as dict.

This dict is printed in fabstup.main.execute using pprint.pprint().

static global_defaults()¶

Create and return default configurations from Fabsetup, Fabric and Invoke defaults.

Extends fabric.config.Config.global_defaults which extends invoke.config.Config.global_defaults().

Returns:: dict with merged defaults.

class fabsetup.main.Fabsetup(*args, **kwargs)¶

Bases: Fab

Fabsetup’s CLI entrypoint and parser configuration.

It is build on top of Fabric’s and Invoke’s core functionality for same.

core_args()¶

Create core arguments.

Overwrites fabric.main.Fab.core_args().

Returns:: List of core args each of type invoke.parser.argument.Argument.

parse_core(argv)¶

parse_cleanup()¶

Add list of known fabsetup addons to program output.

Overwrites invoke.program.Program.parse_cleanup().

load_invoke_tasks()¶

load_fabric_tasks()¶

parse_tasks()¶

Parse leftover args, which are typically tasks & per-task args.

Sets self.parser to the parser used, self.tasks to the parsed per-task contexts, and self.core_via_tasks to a context holding any core flags seen within the task contexts.

Also modifies self.core to include the data from core_via_tasks (so that it correctly reflects any supplied core flags regardless of where they appeared).

New in version 1.0.

update_config()¶

Update the previously instantiated .Config with parsed data.

For example, this is how --echo is able to override the default config value for run.echo.

Parameters:: merge (bool) – Whether to merge at the end, or defer. Primarily useful for subclassers. Default: True.

New in version 1.0.

control_output()¶

control_outfile()¶

execute()¶: Add hooks to invoke.program. in order to run external command before fabsetup task execution, control output and outfile of fabsetup task execution and show effective fabsetup config.

run(argv=None, exit=True)¶

print_version()¶

task_list_opener(*args, **kwargs)¶

print_help()¶

fabsetup.print¶

fabsetup.print.print_default(*args, **kwargs)¶

fabsetup.print.print_heading(*args, **kwargs)¶

fabsetup.print.print_docstring(*args, **kwargs)¶

fabsetup.print.print_code_block(*args, **kwargs)¶

fabsetup.print.print_command_line(*args, **kwargs)¶

fabsetup.task¶

fabsetup.task.issue_16_workaround(context)¶

In a given context set the os ssh-agent socket filename if it exists.

Workaround for Fabric issue 16 provided by max-arnold.

Parameters:: context (invoke.context.Context) – The given context.

Example:

>>> # Note: issue_16_workaround() is applied in
>>> #       fabsetup.task.task()
>>> #       so this example uses fabric's task
>>> from fabric import task
>>> @task
... def mytask(c):
...     # c is of type `fabric.connection.Connection` which is
...     # derived from `invoke.context.Context`
...     issue_16_workaround(c)
...     c.run('uname -a')

fabsetup.task.issue_833_workaround()¶

Assign inspect.getfullargspec to inspect.getargspec if it not exists.

Workaround for Invoke issue 833 provided by ian-em.

fabsetup.task.from_config(config, path, default)¶

fabsetup.task.increment_numbered_state(c)¶

fabsetup.task.append_numbered_index(c)¶

fabsetup.task.remove_numbered_index(c)¶

fabsetup.task.get_task_depth(c, default=1)¶

fabsetup.task.wrapped_run_method(c, run_method, remote, **kwargs)¶

Wrap run_method with internal function cmd_in_markdown_codeblock().

A call of such a wrapped run method (c.run() or c.local()) prints out its command and output inside of a markdown codeblock.

Parameters:

run_method – Required, c.run(), or c.local()
remote (bool) – Required, if True, run_method is treated as a run() method, if False, as a local() method.
prefix_formatter (str) – Optional, default: '\n```{language}\n'
cmd_placeholder (str) – Will be printed instead of the actual``cmd``. Optional, default: None
local_cmd_formatter (str) – Optional, default: '{user}@{host}{prompt_end}{cmd}'
remote_cmd_formatter (str) – Optional, default: '{user}@{host}{prompt_end}{cmd}'
return_code_formatter (str) – Optional, default: '[{return_code}]\n'
postfix_formatter (str) – Optional, default: 3*'`'+'\n'
format_kwargs (dict) – Optional, default: dict(language='', prompt_end='> ')
command_output_prefix (str) – Optional, default: "(stdout) " (without quotation marks).
command_errput_prefix (str) – Optional, default: "(STDERR) " (without quotation marks).

fabsetup.task.task(*args, **kwargs)¶

Decorator based on fabric.tasks.task with the following modifications:

On task execution produce Markdown formatted output:
- print task name as H1 heading by using fabsetup.utils.print_full_name()
- print task docstring as paragraph by using fabsetup.utils.print_doc().
- c.run() and c.local() command calls from inside of a decorated function and its output are printed as markdown codeblocks with the power of fabsetup.task.wrapped_run_method().
The context method c.local() exists and works even when no hosts are given by (Fabric) argument -H, --hosts. In such a case, c.local() and c.run() are the same. This feature is a monkey-patch, addresses Fabric issue 1789, issue 1591, and issue 98.
Apply workaround for Fabric issue 16 by using fabsetup.task.issue_16_workaround().

Wraps and extends Fabric’s @task and Invoke’s @task with the following additional keyword arguments:

Parameters:

name_ (str) – Optionally set a custom task name.
doc (bool) – If True, print the task’s docstring on task execution (default).
prefix_formatter (str) – Optional, default: '\n```{language}\n'
local_cmd_formatter (str) – Optional, default: '{user}@{host}{prompt_end}{cmd}'
remote_cmd_formatter (str) – Optional, default: '{user}@{host}{prompt_end}{cmd}'
return_code_formatter (str) – Optional, default: '[{return_code}]\n'
postfix_formatter (str) – Optional, default: 3*'`'+'\n'
format_kwargs (dict) – Optional, default: dict(language='', prompt_end='> ')
command_output_prefix (str) – Optional, default: "(stdout) " (without quotation marks).
command_errput_prefix (str) – Optional, default: "(STDERR) " (without quotation marks).

Example:

>>> from fabsetup.task import task
>>>
>>> @task()
... def termdown(c):
...     """Install and set up termdown"""
...     c.run('echo setup..')

.>> termdown(c)

# termdown

Install and set up termdown

```
myuser@myhost> echo setup..
setup..
```

fabsetup.task.subtask(*args, **kwargs)¶

Decorator which prints out the name and docstring of the decorated function on execution.

The output is markdown formatted and colored: A cyan colored H2 heading containing the name of the subtask and a non-colored paragraph with the docstring of the subtask.

Parameters:

depth (int) – Optionally set the order of the markdown heading which contains the subtask name. The default is 2.
prefix (str) – Optionally set a custom prefix of the heading, default: '\n## '.
tail (str) – Optionally set a custom tail of the heading, default: '\n'.
doc (bool) – If True (the default) print the docstring as a paragraph.
color (fabsetup.utils.color-function) – Optionally set a custom color of the heading, default: fabsetup.utils.cyan.
name (str) – Optionally define a name which is printed as the heading text instead of the name of the subtask function (default: None).

Example:

>>> import invoke.context
>>> c = invoke.context.Context()
>>>
>>> @subtask
... def mysubtask(c):
...     'This is my subtask'
...     print('foo')
...
>>>
>>> mysubtask(c)
[36m
## mysubtask
[0m
[34mThis is my subtask
[0m
foo

fabsetup API¶

Submodules¶

fabsetup.addons¶

fabsetup.fabfile¶

fabsetup.main¶

fabsetup.print¶

fabsetup.task¶

Fabsetup

Navigation

Related Topics