ORIONIS API REFERENCE

THE ORIONIS API

Build with clarity.

Explore the building blocks of an async-first Python framework. Every module, class, and method — connected, searchable, and ready to build with.

class documentation

Rotate log files using size limits and resolved time suffixes.

Method __init__ Initialize the advanced rotating file handler.
Method _cleanupOldFiles Remove old log files exceeding the backup count.
Method _compressFile Compress the specified file using gzip.
Method _ensureStream Ensure the stream is available and up to date.
Method _observeFailure Observe a recovered sink error without changing rotation behavior.
Method _resolvePath Resolve the full path by replacing the {suffix} placeholder.
Method _rotateFile Rotate the current log file if needed.
Method _shouldRotate Determine whether the log file should be rotated.
Method close Close the handler and release resources.
Method emit Emit a log record.
Instance Variable _cache_monotonic_expiry Cache monotonic expiry value used by AdvancedRotatingFileHandler.
Instance Variable _cleanup_pattern Compiled pattern used to recognize cleanup pattern.
Instance Variable _lock Ensure thread safety for file operations.
Instance Variable _path_cache Store resolved paths for recent suffixes.
Instance Variable _utf8_encoding Whether independent UTF-8 encoding gives the exact appended byte count.
Instance Variable app_root Application root directory.
Instance Variable backup_count Maximum number of backup files to retain.
Instance Variable compress_rotated If True, compress rotated files using gzip.
Instance Variable current_path Filesystem path of the active log file.
Instance Variable current_suffix Suffix identifying the active log-rotation window.
Instance Variable delay If True, delay file opening until the first log record.
Instance Variable encoding File encoding.
Instance Variable file_size File size value used by AdvancedRotatingFileHandler.
Instance Variable max_bytes Maximum file size in bytes before rotation (for chunked rotation).
Instance Variable path_template Path template containing the {suffix} placeholder.
Instance Variable stream Text stream receiving records for the active log file.
Instance Variable suffix_resolver Resolver for determining the suffix for rotation.
def __init__(self, path_template: str, suffix_resolver: SuffixResolver, max_bytes: int | None = None, backup_count: int = 5, encoding: str = 'utf-8', *, delay: bool = True, compress_rotated: bool = False, app_root: str = '.'): (source)

Initialize the advanced rotating file handler.

Parameters
path_template:strPath template containing the {suffix} placeholder.
suffix_resolver:orionis.logging.contracts.suffix_resolver.SuffixResolverResolver for determining the suffix for rotation.
max_bytes:int | None, optionalMaximum file size in bytes before rotation (for chunked rotation).
backup_count:int, optionalMaximum number of backup files to retain.
encoding:str, optionalFile encoding.
delay:bool, optionalIf True, delay file opening until the first log record.
compress_rotated:bool, optionalIf True, compress rotated files using gzip.
app_root:str, optionalApplication root directory.
Returns
NoneThis method does not return a value.
def _cleanupOldFiles(self): (source)

Remove old log files exceeding the backup count.

Count plain and compressed log files independently and retain the newest files up to the configured backup count.

Returns
NoneThis method does not return a value.
def _compressFile(self, file_path: str): (source)

Compress the specified file using gzip.

Parameters
file_path:strPath to the file to compress.
Returns
NoneThis method does not return a value.
def _ensureStream(self): (source)

Ensure the stream is available and up to date.

Checks if log rotation is needed and opens a new stream if required. Updates the current suffix and file size accordingly.

Returns
NoneThis method does not return a value.
def _observeFailure(self, error: BaseException, *, phase: str): (source)

Observe a recovered sink error without changing rotation behavior.

Parameters
error:BaseExceptionRecovered error to submit to the failure runtime.
phase:strLogging operation associated with the failure.
Returns
NoneThis method does not return a value.
def _resolvePath(self, suffix: str) -> str: (source)

Resolve the full path by replacing the {suffix} placeholder.

Parameters
suffix:strSuffix to use for replacing {suffix}.
Returns
strThe fully resolved file path as a string.
def _rotateFile(self): (source)

Rotate the current log file if needed.

This method closes the current stream, compresses the rotated file if enabled, cleans up old log files, and resets the handler's state.

Returns
NoneThis method does not return a value.
def _shouldRotate(self, current_suffix: str) -> bool: (source)

Determine whether the log file should be rotated.

Parameters
current_suffix:strThe suffix already resolved by the caller.
Returns
boolTrue if the file should be rotated, otherwise False.
def close(self): (source)

Close the handler and release resources.

Closes the underlying stream if open and releases any resources held by the handler. Ensures thread safety during the close operation.

Returns
NoneThis method does not return a value.
def emit(self, record: LogRecord): (source)

Emit a log record.

Parameters
record:logging.LogRecordThe log record to emit.
Returns
NoneThis method does not return a value.
_cache_monotonic_expiry: float = (source)

Cache monotonic expiry value used by AdvancedRotatingFileHandler.

_cleanup_pattern: re.Pattern = (source)

Compiled pattern used to recognize cleanup pattern.

Ensure thread safety for file operations.

_path_cache: dict[str, str] = (source)

Store resolved paths for recent suffixes.

_utf8_encoding = (source)

Whether independent UTF-8 encoding gives the exact appended byte count.

app_root = (source)

Application root directory.

backup_count = (source)

Maximum number of backup files to retain.

compress_rotated = (source)

If True, compress rotated files using gzip.

current_path = (source)

Filesystem path of the active log file.

current_suffix = (source)

Suffix identifying the active log-rotation window.

If True, delay file opening until the first log record.

encoding = (source)

File encoding.

file_size = (source)

File size value used by AdvancedRotatingFileHandler.

max_bytes = (source)

Maximum file size in bytes before rotation (for chunked rotation).

path_template = (source)

Path template containing the {suffix} placeholder.

Text stream receiving records for the active log file.

suffix_resolver = (source)

Resolver for determining the suffix for rotation.