cmeta.utils.files module

Reusable functions for safe loading, storing and caching of files

cMeta author and developer: (C) 2025-2026 Grigori Fursin

See the cMeta COPYRIGHT and LICENSE files in the project root for details.

Classes

class cmeta.utils.files.PathLock(lock_file: str, logger=None)

Bases: object

An exclusive lock on a path for processes and threads, through the sidecar file <path>.lock (see the notes above). Use acquire(timeout) / release() or the context manager; is_locked says whether this object holds the lock; mode is how it was taken (‘windows’, ‘flock’, ‘lockf’ or ‘soft’); identity_retries counts the times a replaced lock file was detected and retried.

__init__(lock_file: str, logger=None)

acquire(timeout: float = 3, note: str = None)

Take the lock or raise TimeoutError; returns self. The timeout is the whole wait (the turn of this thread among the threads of the process, then the lock between processes); inf waits until the lock is free; nan is refused (ValueError).

release()

Release the lock and remove its file (when the file at the path is still the one this lock holds).

write_note(note)

Leave a short note in the held lock file - who holds it and why - for the message of a waiter (read_note). Best effort: nothing happens when it cannot be written. The note starts after a first byte that stays free: on Windows that byte is the locked one, which another process cannot read. Not in soft mode, where the file already holds pid host time.

static read_note(lock_file)

The note the holder of lock_file left (write_note), or the pid host time of a soft lock, or ‘’ when there is none or the file cannot be read.

Functions

cmeta.utils.files.acquire_with_notice(lock, timeout: float, subject: str, what: str, env_name: str, note: str = None, logger=None)

Take lock within timeout seconds (inf: until it is free). A waiter that has not got it after LOCK_NOTICE_SECONDS says so in a cMeta warning: line on the standard output, naming the holder when it left a note in the lock file, and keeps waiting for the rest of the time; when the lock stays held, the TimeoutError names the holder and the environment variable that lengthens the wait.

Returns:

the lock, acquired.

Return type:

PathLock

Raises:

• TimeoutError – the lock stayed held for timeout seconds.

• ValueError – the timeout is nan (whether the lock is free or not).

cmeta.utils.files.apply_sharding_to_path(path: str, name: str, slices: list)

Apply sharding to construct a full sharded directory path.

Combines a base path with sharded directory components generated from a name.

Parameters:

• path – Base directory path to prepend to sharded path.

• name – Name to shard.

• slices – List of integers specifying shard lengths (e.g., [2, 2]).

Returns:

Dictionary with ‘return’: 0, ‘sharded_parts’: list of path components,

and ‘sharded_path’: full sharded path string. On error, ‘return’ > 0.

Return type:

dict

Raises:

Exception – Propagated runtime errors, if any.

cmeta.utils.files.ask_to_delete(con, force, path, name=None, text=None, space=False)

Prompt for deletion confirmation in console mode.

Parameters:

• con – If True, print output to console.

• force – If True, force operation.

• path – Filesystem path.

• name – Object or artifact name.

• text – Value for text.

• space – Indentation prefix for console output.

Returns:

Operation result.

Return type:

dict

Raises:

Exception – Propagated runtime errors, if any.

cmeta.utils.files.cpath(path)

Normalize and quote a path string for shell usage.

Parameters:

path – Filesystem path.

Returns:

Operation result.

Return type:

dict

Raises:

Exception – Propagated runtime errors, if any.

cmeta.utils.files.diff_env(old: dict[str, str], new: dict[str, str])

Diff two environment dicts and return added/removed variables.

Parameters:

• old (dict[str, str]) – Old environment dictionary.

• new (dict[str, str]) – New environment dictionary.

Returns:

Dictionary with ‘env_added’ and ‘env_removed’ keys containing

usable environment dictionaries with fuzzy PATH expansion.

Return type:

dict

Raises:

Exception – Propagated runtime errors, if any.

cmeta.utils.files.edit_yaml_text(text: str, data: dict)

Edit the text of a YAML mapping so that it loads as data, touching only the top-level keys whose values changed: the lines of such a key are replaced by a fresh dump of that key (yaml_dump_keep), removed keys are deleted, new keys are appended at the end. Comments, blank lines, quoting, the order of the keys and the line endings everywhere else stay byte-identical. A comment inside or at the end of a value that changed goes with the value.

Parameters:

• text (str) – The YAML text of a file.

• data (dict) – The mapping the text must load as afterwards (string keys).

Returns:

The new text, or None when the text cannot be edited this way: not a block mapping at the top level, several documents, anchors or aliases, duplicate or non-string keys, a parse error. The caller then dumps the whole file.

Return type:

str or None

cmeta.utils.files.files_decode(files_base64)

files_base64: dict {filename: base64_string} returns: dict {filename: binary_bytes}

Parameters:

files_base64 – Value for files base64.

Returns:

Operation result.

Return type:

dict

Raises:

Exception – Propagated runtime errors, if any.

cmeta.utils.files.files_encode(files)

files: list of file paths returns: dict {filename: base64_string}

Parameters:

files – Value for files.

Returns:

Operation result.

Return type:

dict

Raises:

Exception – Propagated runtime errors, if any.

cmeta.utils.files.gen_temp_filepath(template=None)

Generate a temporary file path using an optional template.

Parameters:

template – Value for template.

Returns:

Operation result.

Return type:

dict

Raises:

Exception – Propagated runtime errors, if any.

cmeta.utils.files.get_creation_time(path)

Return creation (or closest available) timestamp for a path.

Parameters:

path – Filesystem path.

Returns:

Operation result.

Return type:

dict

Raises:

Exception – Propagated runtime errors, if any.

cmeta.utils.files.get_latest_modification_time(path)

Return last modification timestamp for a path as a datetime object.

Parameters:

path – Filesystem path.

Returns:

Operation result.

Return type:

dict

Raises:

Exception – Propagated runtime errors, if any.

cmeta.utils.files.get_latest_tree_modification_time(path)

Return the maximum modification time (mtime) of the directory or any file/directory inside it (recursively). Works on Linux, macOS, and Windows.

Parameters:

path – Filesystem path.

Returns:

Operation result.

Return type:

dict

Raises:

Exception – Propagated runtime errors, if any.

cmeta.utils.files.is_dir_empty(path, clean=False)

Check if a directory is empty and optionally remove it.

Parameters:

• path – Filesystem path.

• clean (bool) – If True, remove the directory when it is found to be empty.

Returns:

True if the path is an existing, empty directory, else False.

Return type:

bool

Raises:

Exception – Propagated runtime errors, if any.

cmeta.utils.files.is_dir_within_path(base: str, directory: str)

Check whether a child directory name resolves under a base path.

Parameters:

• base – Value for base.

• directory – Directory path.

Returns:

Operation result.

Return type:

dict

Raises:

Exception – Propagated runtime errors, if any.

cmeta.utils.files.is_path_within(base: str, target: str)

Check if base path is within target path.

Determines if the base path is a subdirectory or file within the target path.

Parameters:

• base (str) – Base path to check.

• target (str) – Target path to check against.

Returns:

True if base is within target, False otherwise.

Return type:

bool

Raises:

Exception – Propagated runtime errors, if any.

cmeta.utils.files.load_files(path, load_files, fail_on_error=False, logger=None, timeout=1)

Load selected files from a directory using safe readers.

Parameters:

• path – Filesystem path.

• load_files – Value for load files.

• fail_on_error – Value for fail on error.

• logger – Value for logger.

• timeout – Timeout value in seconds.

Returns:

Operation result.

Return type:

dict

Raises:

Exception – Propagated runtime errors, if any.

cmeta.utils.files.lock_path(path: str, timeout: float = None, fail_on_error: bool = False, logger=None)

Acquire a lock on a file or directory path.

Parameters:

• path (str) – Path to lock (file or directory).

• timeout (int) – Seconds to wait for lock acquisition. Default is 3.

• fail_on_error (bool) – If True, raises exception on error instead of returning error dict.

• logger – Optional logger for debug messages.

Returns:

Dictionary with ‘return’: 0 and ‘file_lock’ on success,

or ‘return’ > 0 and ‘error’ on failure.

Return type:

dict

Raises:

Exception – Propagated runtime errors, if any.

cmeta.utils.files.lock_timeout(default: float = 30, env_name: str = 'CMETA_LOCK_TIMEOUT', logger=None)

The seconds a writer waits for a lock: default (LOCK_TIMEOUT, 30 s, for the lock of a file) unless the environment variable env_name (CMETA_LOCK_TIMEOUT) holds a number of seconds; a value that is not a number (a word, nan) is ignored with a warning. inf is no limit.

Returns:

The seconds (0 or more; inf: until the lock is free).

Return type:

float

cmeta.utils.files.md5sum(path, chunk_size=100000)

Calculate md5sum

Parameters:

• path – Filesystem path.

• chunk_size – Number of bytes to read per iteration when hashing file content.

Returns:

• return (int): return code == 0 if no error and >0 if error

• (error) (str): error string if return>0

• md5sum (str): md5sum of the give file

Return type:

(CM return dict)

Raises:

Exception – Propagated runtime errors, if any.

cmeta.utils.files.order_meta_keys(data)

A copy of a meta mapping with the keys of YAML_META_KEY_ORDER first, in that order, and every other key after them in the order given (the order of a new _cmeta.yaml).

Parameters:

data – A mapping; anything else is returned unchanged.

Returns:

The reordered (shallow) copy.

Return type:

dict

cmeta.utils.files.parse_env_dump(data: str) → dict[str, str]

Parse KEY=VALUE lines into an environment dictionary.

Parameters:

data – Input data object.

Returns:

Result value.

Return type:

dict[str, str]

Raises:

Exception – Propagated runtime errors, if any.

cmeta.utils.files.quote_path(path)

Add double quotes around a path when it contains spaces.

Parameters:

path – Filesystem path.

Returns:

Operation result.

Return type:

dict

Raises:

Exception – Propagated runtime errors, if any.

cmeta.utils.files.quote_path2(path)

Add double quotes with around a path when it contains spaces. Useful for sub-tools such as adb or rcp

Parameters:

path – Filesystem path.

Returns:

Operation result.

Return type:

dict

Raises:

Exception – Propagated runtime errors, if any.

cmeta.utils.files.read_file(filepath: str, fail_on_error: bool = False, logger=None, encoding: str = None, remove_after_read: bool = False)

Read file without locking (convenience wrapper for safe_read_file).

Parameters:

• filepath (str) – Path to the file to read.

• fail_on_error (bool) – If True, raises exception on error instead of returning error dict.

• logger – Optional logger for debug messages.

• encoding (str | None) – Character encoding for text files.

• remove_after_read (bool) – If True, attempt to remove the file after reading it.

Returns:

Dictionary with ‘return’: 0 and ‘data’, or ‘return’ > 0 and ‘error’.

Return type:

dict

Raises:

Exception – Propagated runtime errors, if any.

cmeta.utils.files.remove_dirs_from_path(path: str, num: int = 0)

Remove trailing directory levels from a path.

Parameters:

• path (str) – Starting filesystem path.

• num (int) – Number of parent directory levels to remove.

Returns:

A successful cMeta return dictionary containing the resulting path.

Return type:

dict

cmeta.utils.files.remove_files_and_dirs_in_path(path, pattern='*', ignore=None)

Recursively remove files and directories in path matching pattern, while ignoring any names matching items in ignore.

Parameters:

• path (str or Path) – Root directory to operate on.

• pattern (str) – Wildcard pattern (fnmatch-style) to match files/directories.

• ignore (list[str], optional) – List of wildcard patterns for files/directories to ignore. Matching is done against the basename.

Examples

remove_files_and_dirs_in_path(

path=”.”, pattern=”.log”, ignore=[“keep.log”, “important_”]

)

Parameters:

• path – Filesystem path.

• pattern – Value for pattern.

• ignore – Value for ignore.

Returns:

Operation result.

Return type:

dict

Raises:

Exception – Propagated runtime errors, if any.

cmeta.utils.files.safe_delete_directory(dirpath: str, timeout: float = None, fail_on_error: bool = False, logger=None, file_lock=None)

Safely and recursively deletes a directory with all its contents. Works cross-platform (Windows, Linux, MacOS) and handles special cases like .git directories with read-only attributes.

If lock acquisition fails but directory doesn’t exist, returns success.

Parameters:

• dirpath (str) – Full path to directory to delete.

• timeout (int) – Lock timeout in seconds.

• fail_on_error (bool) – Whether to raise exceptions or return error dict.

• logger – Logger instance for debug messages.

• file_lock – The folder’s lock when the caller holds it already (a delete that first removes the index record under the same lock); the caller releases it.

Returns:

Dict with ‘return’ (0=success, non-zero=error) and optional ‘error’.

Raises:

Exception – Propagated runtime errors, if any.

cmeta.utils.files.safe_delete_directory_if_empty(dirpath: str)

Delete directory only if it’s empty (no files or subdirectories).

Quickly checks if directory is empty and removes it. Ignores all errors (permissions, race conditions, etc.) for safe cleanup operations.

Parameters:

dirpath (str) – Path to the directory to potentially delete.

Returns:

Operation result.

Return type:

dict

Raises:

Exception – Propagated runtime errors, if any.

cmeta.utils.files.safe_delete_directory_if_empty_with_sharding(artifact_path: str, sharding_slices: list = None)

Safely delete empty directories up the hierarchy based on sharding configuration.

Parameters:

• artifact_path (str) – Path to the artifact directory.

• sharding_slices (list | None) – Sharding configuration from category meta.

Returns:

A cMeta dictionary with the following keys

• return (int): 0 if success, >0 if error.

• error (str): Error message if return > 0.

Return type:

dict

Raises:

Exception – Propagated runtime errors, if any.

cmeta.utils.files.safe_json_dumps(obj, sobj='#NON-SERIALIZABLE#', **kwargs)

Serialize an object to JSON while replacing unsupported values.

Parameters:

• obj – Object to serialize.

• sobj (str) – Replacement value for objects that JSON cannot serialize.

• **kwargs – Additional keyword arguments forwarded to json.dumps.

Returns:

Serialized JSON text.

Return type:

str

cmeta.utils.files.safe_read_file(filepath: str, encoding: str = None, lock: bool = False, keep_locked: bool = False, timeout: float = None, retry_if_not_found: int = 0, fail_on_error: bool = False, logger=None, get_last_modified: bool = False)

Safely read file with optional locking and retry logic.

Provides thread/process-safe file reading with file locking support. Cleans up lock on error. If keep_locked=True and lock=True, maintains the lock after successful read (caller must release).

WARNING: This function uses blocking I/O operations. Not suitable for async contexts - use aiofiles and async locking instead.

Parameters:

• filepath – Path to the file to read.

• encoding – Character encoding for text files. If None, auto-detected.

• lock – If True, acquires file lock before reading.

• keep_locked – If True with lock=True, keeps lock after read (returns in result).

• timeout – With a lock, seconds to wait for it (None: the engine’s lock timeout, see lock_timeout); without a lock, how long a read that fails is retried (None: READ_RETRY_SECONDS; 0: one try).

• retry_if_not_found – Number of retry attempts if file not found.

• fail_on_error – If True, raises exception on error instead of returning error dict.

• logger – Optional logger for debug messages.

• get_last_modified (bool) – If True, include file modification timestamp in the result.

Returns:

Dictionary with ‘return’: 0, ‘data’, ‘filepath’, and optionally ‘last_modified’

and ‘file_lock’ (if keep_locked=True). Returns ‘return’ > 0 and ‘error’ on failure.

Return type:

dict

Raises:

Exception – Propagated runtime errors, if any.

cmeta.utils.files.safe_read_file_via_cache(filepath: str, cache: dict, timeout: int = 10, fail_on_error: bool = False, logger=None)

Reads a file with caching keyed by the file’s modification time in nanoseconds, size and inode (an atomic replace changes the inode): the file is read again when any of them changed, which catches two writes within one tick of a coarse file system too. A file read before that is missing for a moment (being replaced on a mount whose rename is not atomic, or inside the swap of a full reindex) is retried a few times before “not found”. The cache dict is read and updated under one lock for the threads of one process. The data handed out is the cached object itself - do not change it (Repos.find copies what a caller may edit).

WARNING: This function uses blocking I/O operations.

Parameters:

• filepath (str) – Path to the file to read.

• cache (dict) – Dictionary to store cached data (modified in-place).

• timeout (int) – How long a read that fails is retried, in seconds.

• fail_on_error (bool) – Whether to raise exceptions or return error dict.

• logger – Optional logger for debug messages

Returns:

Dict with ‘return’ (0=success, non-zero=error) and ‘data’ or ‘error’.

Raises:

Exception – Propagated runtime errors, if any.

cmeta.utils.files.safe_read_yaml_or_json(filepath: str, lock: bool = False, keep_locked: bool = False, timeout: float = None, fail_on_error: bool = False, retry_if_not_found: int = 0, logger=None)

Safely reads a YAML or JSON file by trying YAML first, then JSON. Removes any existing extension from filepath and tries .yaml, then .json.

Parameters:

• filepath (str) – Path to file (extension will be ignored/removed).

• lock (bool) – Whether to use file locking.

• keep_locked (bool) – Whether to keep lock after successful read.

• timeout (int) – Lock timeout.

• fail_on_error (bool) – Whether to raise exceptions or return error dict.

• retry_if_not_found (int) – Number of retries if file not found.

• logger – Logger instance for debug messages.

Returns:

Dict with ‘return’ (0=success, non-zero=error) and ‘data’ or ‘error’. If keep_locked=True and lock=True, also returns ‘file_lock’.

Raises:

Exception – Propagated runtime errors, if any.

cmeta.utils.files.safe_write_file(filepath: str, data, timeout: float = None, file_lock=None, atomic: bool = None, encoding: str = None, fail_on_error: bool = False, logger=None, sort_keys: bool = True, preserve: bool = False, keep: bool = False, safe_dump: bool = False)

Safely write data to file with locking and optional atomic write.

Provides thread/process-safe file writing with file locking support. Supports atomic writes via temp file + rename for data integrity.

With preserve, an existing YAML file keeps its text: only the top-level keys whose values changed are rewritten, new keys are appended, and the result is read back and compared with data before it replaces the file (a full dump that keeps the order of the keys and does not rewrap long strings is the fallback). A YAML file that does not exist yet is written in the keep style of a new meta (keep: the key order of YAML_META_KEY_ORDER, nothing folded, lists indented). Other formats are written as without preserve or keep.

WARNING: This function uses blocking I/O operations. Not suitable for async contexts - use aiofiles and async locking instead.

Parameters:

• filepath (str) – Path where file should be written.

• data – Data to write (dict/list for JSON/YAML, any object for pickle/text).

• timeout (float | None) – Seconds to wait for the lock (None: the engine’s lock timeout, see lock_timeout).

• file_lock – Existing lock to use. If None, acquires new lock.

• atomic (bool | None) – True: written next to the target and put in place with one atomic replace (a reader never sees a half-written file; the mode of the target is kept; a symbolic link is written through). None: atomic for JSON, YAML and pickle, in place for text. False: in place.

• encoding (str | None) – Character encoding for text files. If None, auto-detected.

• fail_on_error (bool) – If True, raises exception on error instead of returning error dict.

• logger – Optional logger for debug messages.

• sort_keys (bool) – If True, sorts dictionary keys in JSON/YAML output.

• preserve (bool) – If True, an existing YAML file is edited in place and validated; a new one is written in the keep style.

• keep (bool) – If True, a YAML file is written in the keep style of a new _cmeta.yaml.

Returns:

Dictionary with ‘return’: 0 on success, or ‘return’ > 0 and ‘error’ on failure.

With preserve on an existing YAML file also ‘method’ (‘edit’ or ‘dump’) and ‘validated’.

Return type:

dict

Raises:

Exception – Propagated runtime errors, if any.

cmeta.utils.files.shard_name(name: str, slices=None)

Apply sharding to a single path component.

Generates shard directory names from a name string based on specified slice lengths. If the name is shorter than required, uses underscore-filled placeholders to ensure predictable directory structure.

Parameters:

• name – Name to shard (file or directory name).

• slices – List of integers specifying shard lengths (e.g., [2, 2] creates 2-char shards). None means no sharding.

Returns:

List containing shard directory names followed by the original name.

Example: shard_name(‘example’, [2, 2]) -> [‘ex’, ‘am’, ‘example’]

Return type:

list

Raises:

Exception – Propagated runtime errors, if any.

cmeta.utils.files.unlock_path(path: str, file_lock, fail_on_error: bool = False, logger=None)

Release a lock on a file or directory path.

Parameters:

• path (str) – Path to unlock (file or directory).

• file_lock – FileLock object from lock_path().

• fail_on_error (bool) – If True, raises exception on error instead of returning error dict.

• logger – Optional logger for debug messages.

Returns:

Error dict with ‘return’ > 0 and ‘error’ on failure, None on success.

Return type:

dict

Raises:

Exception – Propagated runtime errors, if any.

cmeta.utils.files.unzip(filename: str, path: str = None, remove_directories: int = 0, skip_directories: list = None, overwrite: bool = True, clean: bool = False, fail_on_error: bool = False)

Extract a ZIP archive to a directory.

Parameters:

• filename (str) – Path to ZIP file to extract.

• path (str | None) – Destination directory (defaults to current directory).

• remove_directories (int) – Number of leading directory levels to strip from paths.

• skip_directories (list | None) – List of directory names to skip during extraction.

• overwrite (bool) – If True, overwrite existing files.

• clean (bool) – If True, delete ZIP file after successful extraction.

• fail_on_error (bool) – If True, raises exception on error instead of returning error dict.

Returns:

Dictionary with ‘return’: 0 on success, or ‘return’ > 0 and ‘error’ on failure.

Return type:

dict

Raises:

Exception – Propagated runtime errors, if any.

cmeta.utils.files.use_soft_lock_under(folder: str)

Ask for the soft lock for every lock file under folder (see the notes on the path lock: a home or repository that several systems write at once through a shared drive, whose OS locks do not see each other). The engine calls it for a repository whose descriptor says lock: soft; the environment variable CMETA_SOFT_LOCK_PATHS names folders at the start of a process. ‘*’ means everywhere.

Returns:

{‘return’: 0}

Return type:

dict

cmeta.utils.files.write_file(filepath: str, data, encoding: str = None, fail_on_error: bool = False, logger=None, sort_keys: bool = True, file_format: str = None, newline: str = '\n', safe_dump: bool = False, keep: bool = False)

Write data to file with format-specific serialization.

Automatically serializes data based on file format (JSON, YAML, pickle, or text).

Args:

filepath (str): Path where file should be written. data: Data to write (dict/list for JSON/YAML, any object for pickle/text). encoding (str | None): Character encoding for text files. If None, auto-detected. fail_on_error (bool): If True, raises exception on error instead of returning error dict. logger: Optional logger for debug messages. sort_keys (bool): If True, sorts dictionary keys in JSON/YAML output. file_format (str | None): Force specific format (‘json’, ‘yaml’, ‘pickle’, ‘text’). If None, auto-detected. newline (str): Newline character for text files. Default is ‘

‘.

safe_dump (bool): Replace non-serializable JSON values with a marker string. keep (bool): Write YAML in the keep style (the style of a new _cmeta.yaml): the keys of

YAML_META_KEY_ORDER first, then the rest in the order given; long strings on one line, multi-line strings as literal blocks, list items indented under their key. JSON, pickle and text are written as without it.

Returns:

dict: Dictionary with ‘return’: 0 on success, or ‘return’ > 0 and ‘error’ on failure.

Raises:

Exception – Propagated runtime errors, if any.

cmeta.utils.files.yaml_dump_keep(data, indent_lists: bool = False)

Dump YAML in the “keep” style: the order of the keys as given, long strings on one line, multi-line strings as literal blocks (YAML_DUMP_KEEP). Used for the parts of an existing file that are rewritten.

Parameters:

• data – Data to dump.

• indent_lists (bool) – If True, the items of a list are indented under their key (” - a”); PyYAML’s default puts them at the key’s column (”- a”).

Returns:

The YAML text, ending with a line break.

Return type:

str

cmeta.utils.files.zip_directory(source_dir: str, output_path: str, skip_directories: list = None, fail_on_error: bool = True, logger=None, skip_files: list = None)

Creates a zip archive from a directory.

Parameters:

• source_dir (str) – Path to the directory to zip.

• output_path (str) – Path where the zip file will be created.

• skip_directories (list | None) – List of directory names or glob patterns to skip (e.g., [‘.git’, ‘__pycache__’, ‘tmp*’]).

• fail_on_error (bool) – Whether to raise exceptions or return error dict.

• logger – Logger instance for debug messages

• skip_files (list) – List of file names or glob patterns to exclude from the archive.

Returns:

Dict with ‘return’ (0=success, non-zero=error) and optional ‘error’.

Raises:

Exception – Propagated runtime errors, if any.

Constants

cmeta.utils.files.ERROR_CODE_FILE_NOT_FOUND = 16

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.__int__(). For floating-point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by ‘+’ or ‘-’ and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer iteral. >>> int(‘0b100’, base=0) 4

cmeta.utils.files.LOCK_IDENTITY_RETRIES = 50

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.__int__(). For floating-point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by ‘+’ or ‘-’ and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer iteral. >>> int(‘0b100’, base=0) 4

cmeta.utils.files.LOCK_NOTE_MAX = 512

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.__int__(). For floating-point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by ‘+’ or ‘-’ and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer iteral. >>> int(‘0b100’, base=0) 4

cmeta.utils.files.LOCK_NOTICE_SECONDS = 3

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.__int__(). For floating-point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by ‘+’ or ‘-’ and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer iteral. >>> int(‘0b100’, base=0) 4

cmeta.utils.files.LOCK_POLL_MAX = 0.025

Convert a string or number to a floating-point number, if possible.

cmeta.utils.files.LOCK_POLL_START = 0.001

Convert a string or number to a floating-point number, if possible.

cmeta.utils.files.LOCK_SOFT_CHECK_SECONDS = 0.25

Convert a string or number to a floating-point number, if possible.

cmeta.utils.files.LOCK_SOFT_DEAD_MIN_AGE_SECONDS = 1.0

Convert a string or number to a floating-point number, if possible.

cmeta.utils.files.LOCK_SOFT_EMPTY_STALE_SECONDS = 2.0

Convert a string or number to a floating-point number, if possible.

cmeta.utils.files.LOCK_SOFT_HEARTBEAT_SECONDS = 2.0

Convert a string or number to a floating-point number, if possible.

cmeta.utils.files.LOCK_SOFT_PATHS_ENV = 'CMETA_SOFT_LOCK_PATHS'

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to ‘utf-8’. errors defaults to ‘strict’.

cmeta.utils.files.LOCK_SOFT_READ_MAX = 1024

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.__int__(). For floating-point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by ‘+’ or ‘-’ and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer iteral. >>> int(‘0b100’, base=0) 4

cmeta.utils.files.LOCK_SOFT_REMOVE_SECONDS = 2.0

Convert a string or number to a floating-point number, if possible.

cmeta.utils.files.LOCK_SOFT_SILENT_SECONDS = 20.0

Convert a string or number to a floating-point number, if possible.

cmeta.utils.files.LOCK_SOFT_STALE_SECONDS = 600

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.__int__(). For floating-point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by ‘+’ or ‘-’ and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer iteral. >>> int(‘0b100’, base=0) 4

cmeta.utils.files.LOCK_SOFT_TAKE_REMOVE_SECONDS = 0.2

Convert a string or number to a floating-point number, if possible.

cmeta.utils.files.LOCK_SOFT_TAKE_TRIES = 25

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.__int__(). For floating-point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by ‘+’ or ‘-’ and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer iteral. >>> int(‘0b100’, base=0) 4

cmeta.utils.files.LOCK_SUFFIX = '.lock'

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to ‘utf-8’. errors defaults to ‘strict’.

cmeta.utils.files.LOCK_TIMEOUT = 30

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.__int__(). For floating-point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by ‘+’ or ‘-’ and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer iteral. >>> int(‘0b100’, base=0) 4

cmeta.utils.files.LOCK_TIMEOUT_ENV = 'CMETA_LOCK_TIMEOUT'

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to ‘utf-8’. errors defaults to ‘strict’.

cmeta.utils.files.PICKLE_PROTOCOL = 4

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.__int__(). For floating-point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by ‘+’ or ‘-’ and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer iteral. >>> int(‘0b100’, base=0) 4

cmeta.utils.files.READ_RETRY_SECONDS = 3

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.__int__(). For floating-point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by ‘+’ or ‘-’ and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer iteral. >>> int(‘0b100’, base=0) 4

cmeta.utils.files.RETRY_DELAY = 0.1

Convert a string or number to a floating-point number, if possible.

cmeta.utils.files.RETRY_DELETE_ATTEMPTS = 5

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.__int__(). For floating-point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by ‘+’ or ‘-’ and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer iteral. >>> int(‘0b100’, base=0) 4

cmeta.utils.files.RETRY_NOT_FOUND_DELAY = 0.025

Convert a string or number to a floating-point number, if possible.

cmeta.utils.files.RETRY_NOT_FOUND_FILE = 10

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.__int__(). For floating-point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by ‘+’ or ‘-’ and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer iteral. >>> int(‘0b100’, base=0) 4

cmeta.utils.files.RETRY_NOT_FOUND_INDEX_FILE = 3

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.__int__(). For floating-point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by ‘+’ or ‘-’ and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer iteral. >>> int(‘0b100’, base=0) 4

cmeta.utils.files.RETRY_TIMESTAMP_FILE = 10

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.__int__(). For floating-point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by ‘+’ or ‘-’ and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer iteral. >>> int(‘0b100’, base=0) 4

cmeta.utils.files.YAML_DUMP_KEEP = {'allow_unicode': True, 'default_flow_style': False, 'sort_keys': False, 'width': 1000000}

dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object’s

(key, value) pairs

dict(iterable) -> new dictionary initialized as if via:

d = {} for k, v in iterable:

d[k] = v

dict(**kwargs) -> new dictionary initialized with the name=value pairs

in the keyword argument list. For example: dict(one=1, two=2)

cmeta.utils.files.YAML_META_KEY_ORDER = ('artifact', 'alias', 'category', 'name', 'tags', 'desc', 'note', 'authors', 'copyright', 'license', 'creation_timestamp', 'last_update_timestamp', 'generator', 'last_generator', 'migrated_to', 'migrated_when', 'min_cmeta_version', 'min_cmeta_version_api', 'last_api_version', 'uses_categories', 'uses_artifacts')

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable’s items.

If the argument is a tuple, the return value is the same object.