2. API Reference¶
This section describes the Python API of the easy-server package. The API is kept stable using the compatibility rules defined for semantic versioning. An exception to this rule are fixes for security issues.
Any functions not described in this section are considered internal and may change incompatibly without warning.
2.1. ServerFile class¶
-
class
easy_server.
ServerFile
(filepath, password=None, use_keyring=True, use_prompting=True, verbose=False, user_defined_schema=None, group_user_defined_schema=None, vault_server_schema=None)[source]¶ A server file that specifies the openly accessible portion of the servers and optionally references a vault file that specifies the secret portion of the servers.
An object of this class is tied to a single server file.
The server file is loaded when this object is initialized. If the server file specifies a vault file, the vault file is also loaded at that point.
Optionally, the user-defined portions of the server and group items in the server file, and the server items in the vault file can be validated against user-provided JSON schema.
For a description of the file formats, see sections Server files and Vault files.
- Parameters
filepath (unicode string) – Path name of the server file. Relative path names are relative to the current directory.
password (unicode string) – Password for the vault file. None indicates that no password has been provided.
use_keyring (bool) – Enable the use of the keyring service for retrieving and storing the password of the vault file.
use_prompting (bool) – Enable the use of password prompting for getting the password of the vault file.
verbose (bool) – Print additional messages. Note that the password prompt (if needed) is displayed regardless of verbose mode.
user_defined_schema (JSON schema) – JSON schema for validating the values of the user-defined portion of server items when loading the server file. None means no schema validation takes place for these items.
group_user_defined_schema (JSON schema) – JSON schema for validating the values of the user-defined portion of group items when loading the server file. None means no schema validation takes place for these items.
vault_server_schema (JSON schema) – JSON schema for validating the values of the server items when loading the vault file. None means no schema validation takes place for these items.
- Raises
ServerFileOpenError – Error opening server file
ServerFileFormatError – Invalid server file format
ServerFileUserDefinedFormatError – Invalid format of user-defined portion of server items in the server file
ServerFileUserDefinedSchemaError – Invalid JSON schema for validating user-defined portion of server items in the server file
ServerFileGroupUserDefinedFormatError – Invalid format of user-defined portion of group items in the server file
ServerFileGroupUserDefinedSchemaError – Invalid JSON schema for validating user-defined portion of group items in the server file
VaultFileOpenError – Error with opening the vault file
VaultFileDecryptError – Error with decrypting the vault file
VaultFileFormatError – Invalid vault file format
VaultFileServerFormatError – Invalid format of server items in the vault file
VaultFileServerSchemaError – Invalid JSON schema for validating server items in the vault file
Attributes:
Absolute path name of the server file.
Absolute path name of the vault file specified in the server file, or None if no vault file was specified.
JSON schema for validating the values of the user-defined portion of server items in the server file, or None.
JSON schema for validating the values of the user-defined portion of group items in the server file, or None.
JSON schema for validating the values of the server items in the vault file, or None.
Methods:
Test whether the vault file is in the encrypted state.
get_server
(nickname)Get server for a given server nickname.
list_servers
(nickname)List the servers for a given server or server group nickname.
List the servers for the default server or group.
List all servers.
-
property
filepath
¶ Absolute path name of the server file.
- Type
-
property
vault_file
¶ Absolute path name of the vault file specified in the server file, or None if no vault file was specified.
Vault files specified with a relative path name are relative to the directory of the server file.
- Type
-
property
user_defined_schema
¶ JSON schema for validating the values of the user-defined portion of server items in the server file, or None.
- Type
-
property
group_user_defined_schema
¶ JSON schema for validating the values of the user-defined portion of group items in the server file, or None.
- Type
-
property
vault_server_schema
¶ JSON schema for validating the values of the server items in the vault file, or None.
- Type
-
is_vault_file_encrypted
()[source]¶ Test whether the vault file is in the encrypted state.
If the server file does not specify a vault file, None is returned.
- Returns
Boolean indicating whether the vault file is in the encrypted state, or None if no vault file was specified.
- Return type
-
get_server
(nickname)[source]¶ Get server for a given server nickname.
- Parameters
nickname (unicode string) – Server nickname.
- Returns
Server with the specified nickname.
- Return type
- Raises
KeyError – Nickname not found
-
list_servers
(nickname)[source]¶ List the servers for a given server or server group nickname.
- Parameters
nickname (unicode string) – Server or server group nickname.
- Returns
List of servers.
- Return type
list of
Server
- Raises
KeyError – Nickname not found
2.2. Server class¶
-
class
easy_server.
Server
(nickname, server_dict, secrets_dict=None)[source]¶ A data object that represents a single server item from a server file, and optionally the corresponding secrets item from a vault file.
Objects of this class are not created by the user, but are returned by methods of the
ServerFile
class.Example for a server item in a server file:
myserver1: # nickname of the server description: "my dev system 1" contact_name: "John Doe" access_via: "VPN to dev network" user_defined: # user-defined part stuff: morestuff
Example for a corresponding secrets item in a vault file:
myserver1: # nickname of the server host: "10.11.12.13" username: myuser1 password: mypass1
- Parameters
nickname (unicode string) – Nickname of the server.
server_dict (dict) – Dictionary with the properties of the server item from the server file, wherein optional properties omitted in the server file have been set to their default values.
secrets_dict (dict) – Dictionary with the properties of the secrets item from the vault file, or None if no vault file is specified in the server file or if the vault file does not contain a corresponding item.
Attributes:
Nickname of the server.
Short description of the server.
Name of technical contact for the server.
Short reminder on the network/firewall/proxy/vpn used to access the server.
Additional user-defined properties for the server.
Secrets defined in the vault file for the server, or None if no vault file is specified in the server file or if the vault file does not contain a corresponding item.
-
property
nickname
¶ Nickname of the server.
- Type
-
property
description
¶ Short description of the server.
This is the value of the
description
property of the server item in the server file.- Type
-
property
contact_name
¶ Name of technical contact for the server.
This is the value of the
contact_name
property of the server item in the server file. It is optional and defaults to None.- Type
-
property
access_via
¶ Short reminder on the network/firewall/proxy/vpn used to access the server.
This is the value of the
access_via
property of the server item in the server file. It is optional and defaults to None.- Type
-
property
user_defined
¶ Additional user-defined properties for the server.
This is the value of the
user_defined
property of the server item in the server file. This value can have an arbitrary user-defined structure. It is optional and defaults to None.- Type
2.3. VaultFile class¶
-
class
easy_server.
VaultFile
(filepath, password=None, use_keyring=True, use_prompting=True, verbose=False, server_schema=None)[source]¶ A vault file that specifies the sensitive portion of servers, i.e. the secrets for accessing the servers.
An object of this class is tied to a single vault file.
For a description of the file format, see section Vault files.
The vault file may be in the encrypted or decrypted state. When data from the vault file is read, the vault file remains unchanged, and the data is is decrypted in memory if the file was in the encrypted state.
Vault file encryption, vault file decryption, and reading data from an encrypted vault file requires a password specific to the vault file. The password can be specified as an init argument to this class, or if not provided will be retrieved the keyring service, or if not found there, will be interactively prompted for. The use of the keyring service (for retrieving and storing) and the use of password prompting can be individually disabled.
Typical use in client programs would be to use the keyring and to specify no password (the default). Typical use in test programs running in a CI/CD system would be to specify a password (from the CI/CD system’s secrets) and not to use the keyring.
- Parameters
filepath (unicode string) – Path name of the vault file.
password (unicode string) – Password for the vault file. None indicates that no password has been provided.
use_keyring (bool) – Enable the use of the keyring service for retrieving and storing the password.
use_prompting (bool) – Enable the use of password prompting for getting the password.
verbose (bool) – Print additional messages. Note that the password prompt (if needed) is displayed regardless of verbose mode.
server_schema (JSON schema) – JSON schema for validating the values of the server items when loading the vault file. None means no schema validation takes place for these items.
- Raises
VaultFileOpenError – Error with opening the vault file
VaultFileDecryptError – Error with decrypting the vault file
VaultFileFormatError – Invalid vault file format
VaultFileServerFormatError – Invalid format of server items in the vault file
VaultFileServerSchemaError – Invalid JSON schema for validating the server items in the vault file
Attributes:
Path name of the vault file.
Server nicknames in the vault file.
JSON schema for validating the values of the server items, or None.
Methods:
Return whether the vault file is encrypted.
get_secrets
(nickname)Get the secrets item from the vault file for a given server nickname.
-
property
filepath
¶ Path name of the vault file.
- Type
-
property
nicknames
¶ Server nicknames in the vault file.
- Type
list of string
-
property
server_schema
¶ JSON schema for validating the values of the server items, or None.
- Type
-
is_encrypted
()[source]¶ Return whether the vault file is encrypted.
- Returns
Boolean indicating whether the vault file is encrypted.
- Return type
-
get_secrets
(nickname)[source]¶ Get the secrets item from the vault file for a given server nickname.
Example
Using the following vault file:
secrets: # Fixed key myserver1: # Nickname of the server host: "10.11.12.13" # User-defined secrets username: myusername password: mypassword
The return value for
nickname='myserver1'
will be:dict( 'host': '10.11.12.13', 'username': 'myusername, 'password': 'mypassword', )
- Parameters
nickname (unicode string) – Server nickname.
- Returns
Copy of the secrets item for that server from the vault file.
- Return type
- Raises
KeyError – Nickname not found in the vault file.
2.4. Exception classes¶
-
class
easy_server.
ServerFileException
[source]¶ Abstract base exception for errors related to server files.
Derived from
Exception
.
-
class
easy_server.
ServerFileOpenError
[source]¶ Exception indicating that a server file was not found or cannot be accessed due to a permission error.
Derived from
ServerFileException
.
-
class
easy_server.
ServerFileFormatError
[source]¶ Exception indicating that an existing server file has some issue with the format of its file content.
Derived from
ServerFileException
.
-
class
easy_server.
ServerFileUserDefinedFormatError
[source]¶ Exception indicating that the values of the user-defined portion of server items in a server file do not match the JSON schema defined for them.
Derived from
ServerFileException
.
-
class
easy_server.
ServerFileUserDefinedSchemaError
[source]¶ Exception indicating that the JSON schema for validating the values of the user-defined portion of server items in a server file is not a valid JSON schema.
Derived from
ServerFileException
.
-
class
easy_server.
ServerFileGroupUserDefinedFormatError
[source]¶ Exception indicating that the values of the user-defined portion of group items in a server file do not match the JSON schema defined for them.
Derived from
ServerFileException
.
-
class
easy_server.
ServerFileGroupUserDefinedSchemaError
[source]¶ Exception indicating that the JSON schema for validating the values of the user-defined portion of group items in a server file is not a valid JSON schema.
Derived from
ServerFileException
.
-
class
easy_server.
VaultFileException
[source]¶ Abstract base exception for errors related to vault files.
Derived from
Exception
.
-
class
easy_server.
VaultFileOpenError
[source]¶ Exception indicating that a vault file was not found or cannot be accessed for reading due to a permission error.
Derived from
VaultFileException
.
-
class
easy_server.
VaultFileDecryptError
[source]¶ Exception indicating that an encrypted vault file could not be decrypted.
Derived from
VaultFileException
.
-
class
easy_server.
VaultFileFormatError
[source]¶ Exception indicating that an existing vault file has some issue with the format of its file content.
Derived from
VaultFileException
.
-
class
easy_server.
VaultFileServerFormatError
[source]¶ Exception indicating that the values of the server items in a vault file do not match the JSON schema defined for them.
Derived from
VaultFileException
.
-
class
easy_server.
VaultFileServerSchemaError
[source]¶ Exception indicating that the JSON schema for validating the values of the server items in a vault file is not valid.
Derived from
VaultFileException
.