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 bypackaging.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
- label – A string. The configuration identified by
-
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: - label – A string. The configuration identified by
-
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
- 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
-
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 innailgun.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
andpost
, accept anauth
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 thenailgun.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 anauth
orverify
attribute.
-
classmethod
-
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.
- xdg_config_dir – A string. The name of the directory that is suffixed
to the end of each of the