`nailgun.config`¶

Tools for managing and presenting server connection configurations.

NailGun needs to know certain facts about the remote server in order to do anything useful. For example, NailGun needs to know the URL of the remote server (e.g. ‘https://example.com:250’) and how to authenticate with the remote server. nailgun.config.ServerConfig eases the task of managing and presenting that information.

class nailgun.config.BaseServerConfig(url, auth=None, version=None)¶

A set of facts for communicating with a Satellite server.

This object stores a set of facts that can be used when communicating with a Satellite server, regardless of whether that communication takes place via the API, CLI or UI. nailgun.config.ServerConfig is more specialized and adds attributes that are useful when communicating with the API.

Parameters:

url – A string. The URL of a server. For example: ‘https://example.com:250’.
auth – Credentials to use when communicating with the server. For example: (‘username’, ‘password’). No instance attribute is created if no value is provided.
version –
A string, such as '6.0' or '6.1', indicating the Satellite version the server is running. This version number is parsed by packaging.version.parse before being stored locally. This allows for version comparisons:
```
>>> from nailgun.config import ServerConfig
>>> from packaging.version import parse
>>> cfg = ServerConfig('http://sat.example.com', version='6.0')
>>> cfg.version == parse('6.0')
True
>>> cfg.version == parse('6.0.0')
True
>>> cfg.version < parse('10.0')
True
>>> '6.0' < '10.0'
False
```
If no version number is provided, then no instance attribute is created, and it is assumed that the server is running an up-to-date nightly build.

Warning

This class will likely be moved to a separate Python package in a future release of NailGun. Be careful about making references to this class, as those references will likely need to be changed.

classmethod delete(label='default', path=None)¶

Delete a server configuration.

This method is thread safe.

Parameters:	label – A string. The configuration identified by `label` is deleted. path – A string. The configuration file to be manipulated. Defaults to what is returned by `nailgun.config._get_config_file_path()`.
Returns:	`None`

classmethod get(label='default', path=None)¶

Read a server configuration from a configuration file.

Parameters:	label – A string. The configuration identified by `label` is read. path – A string. The configuration file to be manipulated. Defaults to what is returned by `nailgun.config._get_config_file_path()`.
Returns:	A brand new `nailgun.config.BaseServerConfig` object whose attributes have been populated as appropriate.
Return type:	BaseServerConfig

classmethod get_labels(path=None)¶

Get all server configuration labels.

Parameters:	path – A string. The configuration file to be manipulated. Defaults to what is returned by `nailgun.config._get_config_file_path()`.
Returns:	Server configuration labels, where each label is a string.

save(label='default', path=None)¶

Save the current connection configuration to a file.

This method is thread safe.

Parameters:

label – A string. An identifier for the current configuration. This allows multiple configurations with unique labels to be saved in a single file. If a configuration identified by label already exists in the destination configuration file, it is replaced.
path – A string. The configuration file to be manipulated. By default, an XDG-compliant configuration file is used. A configuration file is created if one does not exist already.

Returns:

None

exception nailgun.config.ConfigFileError¶: Indicates an error occurred when locating a configuration file.

Warning

This class will likely be moved to a separate Python package in a future release of NailGun. Be careful about making references to this class, as those references will likely need to be changed.

class nailgun.config.ServerConfig(url, auth=None, version=None, verify=None)¶

Extend nailgun.config.BaseServerConfig.

This class adds functionality that is useful specifically when working with the API. For example, it stores the additional verify instance attribute and adds logic useful for presenting information to the methods in nailgun.client.

Parameters:	verify – A boolean. Should SSL be verified when communicating with the server? No instance attribute is created if no value is provided.

classmethod get(label='default', path=None)¶

Read a server configuration from a configuration file.

This method extends nailgun.config.BaseServerConfig.get(). Please read up on that method before trying to understand this one.

The entity classes rely on the requests library to be a transport mechanism. The methods provided by that library, such as get and post, accept an auth argument. That argument must be a tuple:

Auth tuple to enable Basic/Digest/Custom HTTP Auth.

However, the JSON decoder does not recognize a tuple as a type, and represents sequences of elements as a tuple. Compensate for that by converting auth to a two element tuple if it is a two element list.

This override is done here, and not in the base class, because the base class may be extracted out into a separate library and used in other contexts. In those contexts, the presence of a list may not matter or may be desirable.

get_client_kwargs()¶

Get kwargs for use with the methods in nailgun.client.

This method returns a dict of attributes that can be unpacked and used as kwargs via the ** operator. For example:

cfg = ServerConfig.get()
client.get(f'{cfg.url}/api/v2', **cfg.get_client_kwargs())

This method is useful because client code may not know which attributes should be passed from a ServerConfig object to one of the nailgun.client functions. Consider that the example above could also be written like this:

cfg = ServerConfig.get()
client.get(f'{cfg.url}/api/v2', auth=cfg.auth, verify=cfg.verify)

But this latter approach is more fragile. It will break if cfg does not have an auth or verify attribute.

nailgun.config._get_config_file_path(xdg_config_dir, xdg_config_file)¶

Search XDG_CONFIG_DIRS for a config file and return the first found.

Search each of the standard XDG configuration directories for a configuration file. Return as soon as a configuration file is found. Beware that by the time client code attempts to open the file, it may be gone or otherwise inaccessible.

Parameters:	xdg_config_dir – A string. The name of the directory that is suffixed to the end of each of the `XDG_CONFIG_DIRS` paths. xdg_config_file – A string. The name of the configuration file that is being searched for.
Returns:	A `str` path to a configuration file.
Raises:	nailgun.config.ConfigFileError – When no configuration file can be found.

`nailgun.config`¶

NailGun

Navigation

Related Topics

nailgun.config¶

`nailgun.config`¶