patroni.validator module

Patroni configuration validation helpers.

This module contains facilities for validating configuration of Patroni processes.

var schema

configuration schema of the daemon launched by patroni command.

class _patroni.validator.AtMostOne(*args: str_) View on GitHub

Bases: object + Mark that at most one option from a Case can be suplied. + Represents a list of possible configuration options in a given scope, where at most one can actually be provided. + Note

It should be used together with a link:#patroni.validator.Case[`+Case+`] object.
+
\\__init\\__(_*args:  https://docs.python.org/3/library/stdtypes.html#str[str]_) →  https://docs.python.org/3/library/constants.html#None[None] https://github.com/zalando/patroni/blob/3d527f5728fa8c6fadc55284cf854eead6a30a9b/patroni/validator.py#L393-L410[View on GitHub]link:#patroni.validator.AtMostOne.\\__init\\__[];;
  Create a :class`AtMostOne` object.
  +
Parameters

*args – any arguments that the caller wants to be stored in this Or object.

Example
AtMostOne("nofailover", "failover_priority"): Case({
    "nofailover": bool,
    "failover_priority": IntValidator(min=0, raise_assert=True),
})
+
The :class`AtMostOne` object is used to define that at most one of `+nofailover+` and `+failover_priority+` can be provided.
class _patroni.validator.BinDirectory(_contains: List[ str] | None = None, contains_executable: List[ str] | None = None) View on GitHub

Bases: Directory + Check if a Postgres binary directory contains the expected files. + It is a subclass of Directory with an extended capability: translating BINARIES according to configured postgresql.bin_name, if any. +

Variables:

BINARIES – list of executable files that should exist directly under a given Postgres binary directory. +

BINARIES_ = ['pg_ctl', 'initdb', 'pg_controldata', 'pg_basebackup', 'postgres', 'pg_isready']_

+

validate(name: str) → Iterator[Result] View on GitHub

Check if the expected executables can be found under name binary directory. +

Parameters

name – path to the base directory against which executables will be validated. Check against PATH if name is not provided.

Yields

objects with the error message related to the failure, if any check fails.

class _patroni.validator.Case(_schema: Dict[ str, Any]) View on GitHub

Bases: object + Map how a list of available configuration options should be validated. + Note

It should be used together with an link:#patroni.validator.Or[`+Or+`] object. The link:#patroni.validator.Or[`+Or+`] object will define the list of possible configuration options in a given context, and the link:#patroni.validator.Case[`+Case+`] object will dictate how to validate each of them, if they are set.
+
\\__init\\__(_schema:  https://docs.python.org/3/library/typing.html#typing.Dict[Dict][ https://docs.python.org/3/library/stdtypes.html#str[str],  https://docs.python.org/3/library/typing.html#typing.Any[Any]]_) →  https://docs.python.org/3/library/constants.html#None[None] https://github.com/zalando/patroni/blob/3d527f5728fa8c6fadc55284cf854eead6a30a9b/patroni/validator.py#L332-L351[View on GitHub]link:#patroni.validator.Case.\\__init\\__[];;
  Create a link:#patroni.validator.Case[`+Case+`] object.
  +
  Parameters:::
    *schema* – the schema for validating a set of attributes that may be available in the configuration. Each key is the configuration that is available in a given scope and that should be validated, and the related value is the validation function or expected type.
  Example:::
Case({
    "host": validate_host_port,
    "url": str,
})

+ That will check that host configuration, if given, is valid based on validate_host_port(), and will also check that url configuration, if given, is a str instance.

class _patroni.validator.Directory(_contains: List[ str] | None = None, contains_executable: List[ str] | None = None) View on GitHub

Bases: object + Check if a directory contains the expected files. + The attributes of objects of this class are used by their validate() method. +

Parameters:

+

__init\\__(contains: List[ str] | None = None, contains_executable: List[ str] | None = None) → None View on GitHub

Create a Directory object. +

Parameters

+

check_executables(_path: str | None = None) → Iterator[Result] View on GitHub

Check that all executables from contains_executable list exist within the given directory or within PATH. +

Parameters

path – optional path to the base directory against which executables will be validated. If not provided, check within PATH.

Yields

objects with the error message containing the name of the executable, if any check fails. +

validate(name: str) → Iterator[Result] View on GitHub

Check if the expected paths and executables can be found under name directory. +

Parameters

name – path to the base directory against which paths and executables will be validated. Check against PATH if name is not provided.

Yields

objects with the error message related to the failure, if any check fails.

class _patroni.validator.EnumValidator(_allowed_values: Tuple[ str, …​], case_sensitive: bool = False, raise_assert: bool = False) View on GitHub

Bases: object + Validate enum setting +

Variables:

+

__init\\__(allowed_values: Tuple[ str, …​], case_sensitive: bool = False, raise_assert: bool = False) → None View on GitHub

Create an EnumValidator object with given allowed values. +

Parameters
class _patroni.validator.IntValidator(_min: int | None = None, max: int | None = None, base_unit: str | None = None, expected_type: Any = None, raise_assert: bool = False) View on GitHub

Bases: object + Validate an integer setting. +

Variables:

+

__init\\__(min: int | None = None, max: int | None = None, base_unit: str | None = None, expected_type: Any = None, raise_assert: bool = False) → None View on GitHub

Create an IntValidator object with the given rules. +

Parameters
class _patroni.validator.Optional(_name: str, default: Any | None = None) View on GitHub

Bases: object + Mark a configuration option as optional. +

Variables:

+

__init\\__(name: str, default: Any | None = None) → None View on GitHub

Create an Optional object. +

Parameters
class _patroni.validator.Or(*args: Any_) View on GitHub

Bases: object + Represent the list of options that are available. + It can represent either a list of configuration options that are available in a given scope, or a list of validation functions and/or expected types for a given configuration option. +

__init\\__(*args: Any) → None View on GitHub

Create an Or object. +

Parameters

*args – any arguments that the caller wants to be stored in this Or object.

Example
Or("host", "hosts"): Case({
    "host": validate_host_port,
    "hosts": Or(comma_separated_host_port, [validate_host_port]),
})
+
The outer link:#patroni.validator.Or[`+Or+`] is used to define that `+host+` and `+hosts+` are possible options in this scope. The inner :class`Or` in the `+hosts+` key value is used to define that `+hosts+` option is valid if either of link:#patroni.validator.comma_separated_host_port[`+comma_separated_host_port()+`] or link:#patroni.validator.validate_host_port[`+validate_host_port()+`] succeed to validate it.
class _patroni.validator.Result(_status: bool, error: str | None = "didn’t pass validation", level: int = 0, path: str = '', data: Any = '') View on GitHub

Bases: object + Represent the result of a given validation that was performed. +

Variables:

+

__init\\__(status: bool, error: str | None = "didn’t pass validation", level: int = 0, path: str = '', data: Any = '') → None View on GitHub

Create a Result object based on the given arguments. + Note

`+error+` attribute is only set if _status_ is failed.
+
Parameters:::
class _patroni.validator.Schema(_validator: Any) View on GitHub

Bases: object + Define a configuration schema. + It contains all the configuration options that are available in each scope, including the validation(s) that should be performed against each one of them. The validations will be performed whenever the Schema object is called, or its validate() method is called. +

Variables:

validator
validator of the configuration schema. Can be any of these: +

__init\\__(validator: Any) → None View on GitHub

Create a Schema object. + Note

This class is expected to be initially instantiated with a  https://docs.python.org/3/library/stdtypes.html#dict[`+dict+`] based _validator_ argument. The idea is that dict represents the full YAML tree of configuration options. The link:#patroni.validator.Schema.validate[`+validate()+`] method will then walk recursively through the configuration tree, creating new instances of link:#patroni.validator.Schema[`+Schema+`] with the new “base path”, to validate the structure and the leaf values of the tree. The recursion stops on leaf nodes, when it performs checks of the actual setting values.
+
Parameters:::
  *validator* –
  +
  validator of the configuration schema. Can be any of these:
  +
  The first 3 items in the above list are here referenced as “base validators”, which cause the recursion to stop.
  +
  If _validator_ is a  https://docs.python.org/3/library/stdtypes.html#dict[`+dict+`], then you should follow these rules:
  +
  * For the keys it can be either:
  +
  \\__\\__
  \\__\\__
  * For the values it can be either:
  +
  \\__\\__
  \\__\\__
Example:::
Schema({
    "application_name": str,
    "bind": {
        "host": validate_host,
        "port": int,
    },
    "aliases": [str],
    Optional("data_directory"): "/var/lib/myapp",
    Or("log_to_file", "log_to_db"): Case({
        "log_to_file": bool,
        "log_to_db": bool,
    }),
    "version": Or(int, float),
})


This sample schema defines that your YAML configuration follows these rules:
__\\__ __\\__ +

data_key(_key: str | Optional | Or | AtMostOne) → Iterator[ str] View on GitHub

Map a key from the validator dictionary to the corresponding key(s) in the data dictionary. +

Parameters

key – key from the validator attribute.

Yields

keys that should be used to access corresponding value in the data attribute. +

iter() → Iterator[Result] View on GitHub

Iterate over validator, if it is an iterable object, to validate the corresponding entries in data. + Only dict, list, Directory and Or objects are considered iterable objects. +

Yields

objects with the error message related to the failure, if any check fails. +

iter_dict() → Iterator[Result] View on GitHub

Iterate over a dict based validator to validate the corresponding entries in data. +

Yields

objects with the error message related to the failure, if any check fails. +

iter_or() → Iterator[Result] View on GitHub

Perform all validations defined in an Or object for a given configuration option. + This method can be only called against leaf nodes in the configuration tree. Or objects defined in the validator keys will be handled by iter_dict() method. +

Yields

objects with the error message related to the failure, if any check fails. +

validate(data: Any) → Iterator[Result] View on GitHub

Perform all validations from the schema against the given configuration. + It first checks that data argument type is compliant with the type of validator attribute. +

Additionally

+

Parameters

data – configuration to be validated against validator.

Yields

objects with the error message related to the failure, if any check fails.

patroni.validator.get_type_name(_python_type: Any) → str View on GitHub

Get a user-friendly name for a given Python type. +

Parameters:

python_type – Python type which user friendly name should be taken.

Returns:

User friendly name of the given Python type.

patroni.validator.assert_(condition: bool, message: str = 'Wrong value') → None View on GitHub

Assert that a given condition is True. + If the assertion fails, then throw a message. +

Parameters:
patroni.validator.comma_separated_host_port(string: str) → bool View on GitHub

Validate a list of host and port items. + Call validate_host_port_list() with a list represented by the CSV string. +

Parameters:

string – comma-separated list of host and port items.

Returns:

True if all items in the CSV string are valid.

patroni.validator.data_directory_empty(data_dir: str) → bool View on GitHub

Check if PostgreSQL data directory is empty. +

Parameters:

data_dir – path to the PostgreSQL data directory to be checked.

Returns:

True if the data directory is empty.

patroni.validator.get_bin_name(bin_name: str) → str View on GitHub

Get the value of postgresql.bin_name[*bin_name*] configuration option. +

Parameters:

bin_name – a key to be retrieved from postgresql.bin_name configuration.

Returns:

value of postgresql.bin_name[*bin_name*], if present, otherwise bin_name.

patroni.validator.is_ipv4_address(ip: str) → bool View on GitHub

Check if ip is a valid IPv4 address. +

Parameters:

ip – the IP to be checked.

Returns:

True if the IP is an IPv4 address.

Raises:

ConfigParseError: if ip is not a valid IPv4 address.

patroni.validator.is_ipv6_address(ip: str) → bool View on GitHub

Check if ip is a valid IPv6 address. +

Parameters:

ip – the IP to be checked.

Returns:

True if the IP is an IPv6 address.

Raises:

ConfigParseError: if ip is not a valid IPv6 address.

patroni.validator.validate_binary_name(bin_name: str) → bool View on GitHub

Validate the value of postgresql.binary_name[*bin_name*] configuration option. + If postgresql.bin_dir is set and the value of the bin_name meets these conditions: + __\\__ __\\__ + If postgresql.bin_dir is not set, then validate that the value of bin_name meets this condition: + __\\__ __\\__ +

Parameters:

bin_name – the value of the postgresql.bin_name[*bin_name*]

Returns:

True if the conditions are true

Raises:
patroni.validator.validate_connect_address(address: str) → bool View on GitHub

Check if options related to connection address were properly configured. +

Parameters:

address – address to be validated in the format host:ip.

Returns:

True if the address is valid.

Raises:
patroni.validator.validate_data_dir(data_dir: str) → bool View on GitHub

Validate the value of postgresql.data_dir configuration option. + It requires that postgresql.data_dir is set and match one of following conditions: + __\\__ __\\__ +

Parameters:

data_dir – the value of postgresql.data_dir configuration option.

Returns:

True if the PostgreSQL data directory is valid.

Raises:
patroni.validator.validate_host_port(host_port: str, listen: bool = False, multiple_hosts: bool = False) → bool View on GitHub

Check if host(s) and port are valid and available for usage. +

Parameters:

listen – if the address is expected to be available for binding. False means it expects to connect to that address, and True that it expects to bind to that address. + multiple_hosts – if host_port can contain multiple hosts.

Returns:

True if the host(s) and port are valid.

Raises:
patroni.validator.validate_host_port_list(value: List[ str]) → bool View on GitHub

Validate a list of host(s) and port items. + Call validate_host_port() with each item in value. +

Parameters:

value – list of host(s) and port items to be validated.

Returns:

True if all items are valid.

patroni.validator.validate_host_port_listen(host_port: str) → bool View on GitHub

Check if host and port are valid and available for binding. + Call validate_host_port() with listen set to True. +

Parameters:

host_port – the host and port to be validated. Must be in the format host:ip.

Returns:

True if the host and port are valid and available for binding.

patroni.validator.validate_host_port_listen_multiple_hosts(host_port: str) → bool View on GitHub

Check if host(s) and port are valid and available for binding. + Call validate_host_port() with both listen and multiple_hosts set to True. +

Parameters:

host_port – + the host(s) and port to be validated. It can be in either of these formats

Returns:

True if the host(s) and port are valid and available for binding.

patroni.validator.validate_watchdog_mode(value: Any) → None View on GitHub

Validate watchdog.mode configuration option. +

Parameters:

value – value of watchdog.mode to be validated.


© Copyright 2015 Compose, Zalando SE. Revision 3d527f57.

Built with Sphinx using a theme provided by Read the Docs.

Read the Docs v: master