barman.utils module#

This module contains utility functions used in Barman.

class barman.utils.BarmanEncoder(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)View on GitHub#

Bases: JSONEncoder

Custom JSON encoder used for BackupInfo encoding

This encoder supports the following types:

  • dates and timestamps if they have a ctime() method.

  • objects that implement the ‘to_json’ method.

  • binary strings (python 3)

static _datetime_to_str(obj)View on GitHub#

Serialise date and datetime objects using ctime() method :param obj: :return: None|str

static _decimal_to_float(obj)View on GitHub#

Serialise Decimal objects using their string representation WARNING: When deserialized they will be treat as float values which have a lower precision :param obj: :return: None|float

static _timedelta_to_str(obj)View on GitHub#

Serialise timedelta objects using human_readable_timedelta() :param obj: :return: None|str

static _to_json(obj)View on GitHub#

# If the object implements to_json() method use it :param obj: :return: None|str

static binary_to_str(obj)View on GitHub#

Binary strings must be decoded before using them in an unicode string :param obj: :return: None|str

default(obj)View on GitHub#

Implement this method in a subclass such that it returns a serializable object for o, or calls the base implementation (to raise a TypeError).

For example, to support arbitrary iterators, you could implement default like this:

def default(self, o):
    try:
        iterable = iter(o)
    except TypeError:
        pass
    else:
        return list(iterable)
    # Let the base class default method raise the TypeError
    return JSONEncoder.default(self, o)
method_list = ['_to_json', '_datetime_to_str', '_timedelta_to_str', '_decimal_to_float', 'binary_to_str', 'version_to_str']#
static version_to_str(obj)View on GitHub#

Manage (Loose|Strict)Version objects as strings. :param obj: :return: None|str

class barman.utils.BarmanEncoderV2(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)View on GitHub#

Bases: BarmanEncoder

This class purpose is to replace default datetime encoding from ctime to isoformat (ISO 8601). Next major barman version will use this new format. So this class will be merged back to BarmanEncoder.

static _datetime_to_str(obj)View on GitHub#

Try set output isoformat for this datetime. Date must have tzinfo set. :param obj: :return: None|str

class barman.utils.ChecksumAlgorithmView on GitHub#

Bases: object

_abc_impl = <_abc._abc_data object>#
abstract checksum(value)View on GitHub#

Creates hash hexadecimal string from input byte :param value: Value to create checksum from :type value: byte

Returns:

Return the digest value as a string of hexadecimal digits.

Return type:

str

checksum_from_str(value, encoding='utf-8')View on GitHub#

Creates hash hexadecimal string from input string :param value: Value to create checksum from :type value: str :param encoding: The encoding in which to encode the string. :type encoding: str :return: Return the digest value as a string of hexadecimal digits. :rtype: str

get_name()View on GitHub#
class barman.utils.SHA256View on GitHub#

Bases: ChecksumAlgorithm

_abc_impl = <_abc._abc_data object>#
checksum(value)View on GitHub#

Creates hash hexadecimal string from input byte :param value: Value to create checksum from :type value: byte

Returns:

Return the digest value as a string of hexadecimal digits.

Return type:

str

barman.utils.check_aws_expiration_date_format(value)View on GitHub#

Check user input for aws expiration date timestamp with a specific format.

Parameters:

value – str containing the value to check.

Raises:

ValueError – Fails with an invalid date.

barman.utils.check_aws_snapshot_lock_cool_off_period_range(value)View on GitHub#

Check for AWS Snapshot Lock cool-off period range option

Parameters:

value – str containing the value to check

barman.utils.check_aws_snapshot_lock_duration_range(value)View on GitHub#

Check for AWS Snapshot Lock duration range option

Parameters:

value – str containing the value to check

barman.utils.check_aws_snapshot_lock_mode(value)View on GitHub#

Replication slot names may only contain lower case letters, numbers, and the underscore character. This function parse a replication slot name

Parameters:

value (str) – slot_name value

Returns:

barman.utils.check_backup_name(backup_name)View on GitHub#

Verify that a backup name is not a backup ID or reserved identifier.

Returns the backup name if it is a valid backup name and raises an exception otherwise. A backup name is considered valid if it is not None, not empty, does not match the backup ID format and is not any other reserved backup identifier.

Parameters:

backup_name (str) – The backup name to be checked.

Return str:

The backup name.

barman.utils.check_non_negative(value)View on GitHub#

Check for a positive integer option

Parameters:

value – str containing the value to check

barman.utils.check_positive(value)View on GitHub#

Check for a positive integer option

Parameters:

value – str containing the value to check

barman.utils.check_size(value)View on GitHub#

Check user input for a human readable size

Parameters:

value – str containing the value to check

barman.utils.check_tli(value)View on GitHub#

Check for a positive integer option, and also make “current” and “latest” acceptable values

Parameters:

value – str containing the value to check

barman.utils.configure_logging(log_file, log_level=20, log_format='%(asctime)s %(name)s %(levelname)s: %(message)s')View on GitHub#

Configure the logging module

Parameters:

  • log_file (str,None) – target file path. If None use standard error.

  • log_level (int) – min log level to be reported in log file. Default to INFO

  • log_format (str) – format string used for a log line. Default to “%(asctime)s %(name)s %(levelname)s: %(message)s”

barman.utils.drop_privileges(user)View on GitHub#

Change the system user of the current python process.

It will only work if called as root or as the target user.

Parameters:

user (string) – target user

Raises:

  • KeyError – if the target user doesn’t exists

  • OSError – when the user change fails

barman.utils.edit_config(file, section, option, value, lines=None)View on GitHub#
Utility method that given a file and a config section allows to:

  • add a new section if at least a key-value content is provided

  • add a new key-value to a config section

  • change a section value

Parameters:

  • file (str) – the path to the file to edit

  • section (str) – the config section to edit or to add

  • option (str) – the config key to edit or add

  • value (str) – the value for the config key to update or add

  • lines (list) – optional parameter containing the set of lines of the file to update

Returns:

the updated lines of the file

barman.utils.file_hash(file_path, buffer_size=16384, hash_algorithm='sha256')View on GitHub#

Calculate the checksum for the provided file path with a specific hashing algorithm

Parameters:

  • file_path (str) – path of the file to read

  • buffer_size (int) – read buffer size, default 16k

  • hash_algorithm (str) – sha256 | md5

Return str:

Hexadecimal md5 string

barman.utils.force_str(obj, encoding='utf-8', errors='replace')View on GitHub#

Force any object to an unicode string.

Code inspired by Django’s force_text function

barman.utils.fsync_dir(dir_path)View on GitHub#

Execute fsync on a directory ensuring it is synced to disk

Parameters:

dir_path (str) – The directory to sync

Raises:

OSError – If fail opening the directory

barman.utils.fsync_file(file_path)View on GitHub#

Execute fsync on a file ensuring it is synced to disk

Returns the file stats

Parameters:

file_path (str) – The file to sync

Returns:

file stat

Raises:

OSError – If something fails

barman.utils.get_backup_id_using_shortcut(server, shortcut, BackupInfo)View on GitHub#

Get backup ID from one of Barman shortcuts.

Parameters:

  • server (str) – The obj where to look from.

  • shortcut (str) – pattern to search.

  • BackupInfo (BackupInfo) – Place where we keep some Barman constants.

Return str backup_id|None:

The backup ID for the provided shortcut.

barman.utils.get_backup_info_from_name(backups, backup_name)View on GitHub#

Get the backup metadata for the named backup.

Parameters:

  • backups (list[BackupInfo]) – A list of BackupInfo objects which should be searched for the named backup.

  • backup_name (str) – The name of the backup for which the backup metadata should be retrieved.

Return BackupInfo|None:

The backup metadata for the named backup.

barman.utils.get_log_levels()View on GitHub#

Return a list of available log level names

barman.utils.human_readable_timedelta(timedelta)View on GitHub#

Given a time interval, returns a human readable string

Parameters:

timedelta – the timedelta to transform in a human readable form

barman.utils.is_backup_id(backup_id)View on GitHub#

Checks whether the supplied identifier is a backup ID.

Parameters:

backup_id (str) – The backup identifier to check.

Return bool:

True if the backup matches the backup ID regex, False otherwise.

barman.utils.is_power_of_two(number)View on GitHub#

Check if a number is a power of two or not

barman.utils.lock_files_cleanup(lock_dir, lock_directory_cleanup)View on GitHub#

Get all the lock files in the lock directory and try to acquire every single one. If the file is not locked, remove it.

This method is part of cron and should help keeping clean the lockfile directory.

barman.utils.mkpath(directory)View on GitHub#

Recursively create a target directory.

If the path already exists it does nothing.

Parameters:

directory (str) – directory to be created

barman.utils.parse_log_level(log_level)View on GitHub#

Convert a log level to its int representation as required by logging module.

Parameters:

log_level – An integer or a string

Returns:

an integer or None if an invalid argument is provided

barman.utils.pretty_size(size, unit=1024)View on GitHub#

This function returns a pretty representation of a size value

Parameters:

  • size (int|long|float) – the number to to prettify

  • unit (int) – 1000 or 1024 (the default)

Return type:

str

barman.utils.range_fun(*args, **kwargs)View on GitHub#

Compatibility method required while we still support Python 2.7.

This can be removed when Python 2.7 support is dropped and calling code can reference range directly.

barman.utils.redact_passwords(text)View on GitHub#

Redact passwords from the input text.

Password are found in these two forms:

Keyword/Value Connection Strings: - host=localhost port=5432 dbname=mydb password=SHAME_ON_ME Connection URIs: - postgresql://[user[:password]][netloc][:port][/dbname]

Parameters:

text (str) – Input content

Returns:

String with passwords removed

barman.utils.simplify_version(version_string)View on GitHub#

Simplify a version number by removing the patch level

Parameters:

version_string – the version number to simplify

Return str:

the simplified version number

barman.utils.timeout(timeout_duration)View on GitHub#

ContextManager responsible for timing out the contained block of code after a defined time interval.

barman.utils.timestamp(datetime_value)View on GitHub#

Compatibility method because datetime.timestamp is not available in Python 2.7.

Parameters:

datetime_value (datetime.datetime) – A datetime object to be converted into a timestamp.

Return type:

float

barman.utils.total_seconds(timedelta)View on GitHub#

Compatibility method because the total_seconds method has been introduced in Python 2.7

Parameters:

timedelta – a timedelta object

Return type:

float

barman.utils.which(executable, path=None)View on GitHub#

This method is useful to find if a executable is present into the os PATH

Parameters:

  • executable (str) – The name of the executable to find

  • path (str|None) – An optional search path to override the current one.

Return str|None:

the path of the executable or None

barman.utils.with_metaclass(meta, *bases)View on GitHub#

Function from jinja2/_compat.py. License: BSD.

Create a base class with a metaclass.

Parameters:

meta (type) – Metaclass to add to base class