config

class fabric.config.Config(*args, **kwargs)

An invoke.config.Config subclass with extra Fabric-related behavior.

This class behaves like invoke.config.Config in every way, with the following exceptions:

  • its global_defaults staticmethod has been extended to add/modify some default settings (see its documentation, below, for details);
  • it triggers loading of Fabric-specific env vars (e.g. FABRIC_RUN_HIDE=true instead of INVOKE_RUN_HIDE=true) and filenames (e.g. /etc/fabric.yaml instead of /etc/invoke.yaml).
  • it extends the API to account for loading ssh_config files (which are stored as additional attributes and have no direct relation to the regular config data/hierarchy.)
  • it adds a new optional constructor, from_v1, which generates configuration data from Fabric 1.

Intended for use with Connection, as using vanilla invoke.config.Config objects would require users to manually define port, user and so forth.

New in version 2.0.

__init__(*args, **kwargs)

Creates a new Fabric-specific config object.

For most API details, see invoke.config.Config.__init__. Parameters new to this subclass are listed below.

Parameters:
  • ssh_config – Custom/explicit paramiko.config.SSHConfig object. If given, prevents loading of any SSH config files. Default: None.
  • runtime_ssh_path (str) – Runtime SSH config path to load. Prevents loading of system/user files if given. Default: None.
  • system_ssh_path (str) – Location of the system-level SSH config file. Default: /etc/ssh/ssh_config.
  • user_ssh_path (str) – Location of the user-level SSH config file. Default: ~/.ssh/config.
  • lazy (bool) – Has the same meaning as the parent class’ lazy, but additionally controls whether SSH config file loading is deferred (requires manually calling load_ssh_config sometime.) For example, one may need to wait for user input before calling set_runtime_ssh_path, which will inform exactly what load_ssh_config does.
clone(*args, **kwargs)

Return a copy of this configuration object.

The new object will be identical in terms of configured sources and any loaded (or user-manipulated) data, but will be a distinct object with as little shared mutable state as possible.

Specifically, all dict values within the config are recursively recreated, with non-dict leaf values subjected to copy.copy (note: not copy.deepcopy, as this can cause issues with various objects such as compiled regexen or threading locks, often found buried deep within rich aggregates like API or DB clients).

The only remaining config values that may end up shared between a config and its clone are thus those ‘rich’ objects that do not copy.copy cleanly, or compound non-dict objects (such as lists or tuples).

Parameters:into

A Config subclass that the new clone should be “upgraded” to.

Used by client libraries which have their own Config subclasses that e.g. define additional defaults; cloning “into” one of these subclasses ensures that any new keys/subtrees are added gracefully, without overwriting anything that may have been pre-defined.

Default: None (just clone into another regular Config).

Returns:A Config, or an instance of the class given to into.
Raises:TypeError, if into is given a value and that value is not a Config subclass.

New in version 1.0.

classmethod from_v1(env, **kwargs)

Alternate constructor which uses Fabric 1’s env dict for settings.

All keyword arguments besides env are passed unmolested into the primary constructor, with the exception of overrides, which is used internally & will end up resembling the data from env with the user-supplied overrides on top.

Warning

Because your own config overrides will win over data from env, make sure you only set values you intend to change from your v1 environment!

For details on exactly which env vars are imported and what they become in the new API, please see v1-env-var-imports.

Parameters:env – An explicit Fabric 1 env dict (technically, any fabric.utils._AttributeDict instance should work) to pull configuration from.

New in version 2.4.

static global_defaults()

Default configuration values and behavior toggles.

Fabric only extends this method in order to make minor adjustments and additions to Invoke’s global_defaults; see its documentation for the base values, such as the config subtrees controlling behavior of run or how tasks behave.

For Fabric-specific modifications and additions to the Invoke-level defaults, see our own config docs at Default configuration values.

New in version 2.0.

load_ssh_config()

Load SSH config file(s) from disk.

Also (beforehand) ensures that Invoke-level config re: runtime SSH config file paths, is accounted for.

New in version 2.0.

set_runtime_ssh_path(path)

Configure a runtime-level SSH config file path.

If set, this will cause load_ssh_config to skip system and user files, as OpenSSH does.

New in version 2.0.