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:

`filepath`	Absolute path name of the server file.
`vault_file`	Absolute path name of the vault file specified in the server file, or None if no vault file was specified.
`user_defined_schema`	JSON schema for validating the values of the user-defined portion of server items in the server file, or None.
`group_user_defined_schema`	JSON schema for validating the values of the user-defined portion of group items in the server file, or None.
`vault_server_schema`	JSON schema for validating the values of the server items in the vault file, or None.

Methods:

`is_vault_file_encrypted`()	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_default_servers`()	List the servers for the default server or group.
`list_all_servers`()	List all servers.

property filepath¶

Absolute path name of the server file.

Type: unicode string

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: unicode string

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: JSON schema

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: JSON schema

property vault_server_schema¶

JSON schema for validating the values of the server items in the vault file, or None.

Type: JSON schema

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: bool

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: Server
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

list_default_servers()[source]¶

List the servers for the default server or group.

An omitted ‘default’ element in the server file results in an empty list.

Returns: List of servers.
Return type: list of Server

list_all_servers()[source]¶

List all servers.

Returns: List of servers.
Return type: list of Server

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`	Nickname of the server.
`description`	Short description of the server.
`contact_name`	Name of technical contact for the server.
`access_via`	Short reminder on the network/firewall/proxy/vpn used to access the server.
`user_defined`	Additional user-defined properties for the server.
`secrets`	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: unicode string

property description¶

Short description of the server.

This is the value of the description property of the server item in the server file.

Type: unicode string

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: unicode string

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: unicode string

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: dict

property secrets¶

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.

Type: dict

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:

`filepath`	Path name of the vault file.
`nicknames`	Server nicknames in the vault file.
`server_schema`	JSON schema for validating the values of the server items, or None.

Methods:

`is_encrypted`()	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: unicode string

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: JSON schema

is_encrypted()[source]¶

Return whether the vault file is encrypted.

Returns: Boolean indicating whether the vault file is encrypted.
Return type: bool

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: dict
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.