Collaboration diagram for rotary_logger.rotary_logger_cls.RotaryLogger:

Public Member Functions
None	__init__ (self, bool log_to_file=CONST.LOG_TO_FILE_ENV, bool override=False, str raw_log_folder=CONST.RAW_LOG_FOLDER_ENV, Path default_log_folder=CONST.DEFAULT_LOG_FOLDER, int default_max_filesize=CONST.DEFAULT_LOG_MAX_FILE_SIZE, bool merge_streams=True, *, str encoding=CONST.DEFAULT_ENCODING, bool merge_stdin=False, bool capture_stdin=False, bool capture_stdout=True, bool capture_stderr=True, bool prefix_in_stream=True, bool prefix_out_stream=True, bool prefix_err_stream=True, bool log_function_calls_stdin=False, bool log_function_calls_stdout=False, bool log_function_calls_stderr=False, bool program_log=False, bool program_debug_log=False, bool suppress_program_warning_logs=False, bool suppress_program_error_logs=False)

None	__del__ (self)

None	__call__ (self, Any args, *Any kwds)

None	start_logging (self, *, Optional[Path] log_folder=None, Optional[int] max_filesize=None, Optional[bool] merged=None, bool log_to_file=True, Optional[bool] merge_stdin=None, bool skip_redirect_check_stdin=False, bool skip_redirect_check_stdout=False, bool skip_redirect_check_stderr=False)

bool	pause_logging (self, *, bool toggle=True)

bool	resume_logging (self, *, bool toggle=False)

bool	is_redirected (self, CONST.StdMode stream)

bool	is_logging (self)

None	stop_logging (self)

Data Fields
bool	log_to_file = log_to_file

Path	raw_log_folder = Path(raw_log_folder)

Path	default_log_folder = default_log_folder

int	default_max_filesize = default_max_filesize

CONST.Prefix	prefix = CONST.Prefix()

FileInstance	file_data = FileInstance(None)

bool	capture_stdin = capture_stdin

bool	capture_stdout = capture_stdout

bool	capture_stderr = capture_stderr

	log_function_calls_stdin = log_function_calls_stdin

	log_function_calls_stdout = log_function_calls_stdout

	log_function_calls_stderr = log_function_calls_stderr

Optional[TeeStream]	stdout_stream = None

Optional[TeeStream]	stderr_stream = None

Optional[TeeStream]	stdin_stream = None

bool	paused = False

	program_log = program_log

	program_debug_log = program_debug_log

	suppress_program_warning_logs = suppress_program_warning_logs

	suppress_program_error_logs = suppress_program_error_logs

Rogger	rogger = RI

Path	_file_lock = self.default_log_folder

FileInstance	_file_lock = self.file_data.get_override()

str	raw_log_folder = self.default_log_folder

Path	log_to_file = self._verify_user_log_path(_raw_folder)

Optional[TeeStream]	_file_lock = self.stderr_stream

tuple	_file_lock

Protected Member Functions
int	_get_user_max_file_size (self)

Path	_verify_user_log_path (self, Path raw_log_folder=CONST.DEFAULT_LOG_FOLDER)

Path	_resolve_log_folder (self, Optional[Path] log_folder)

None	_handle_stream_assignments (self, Path log_folder)

None	_resume_logging_locked (self, List[TeeStream] to_flush)

None	_pause_logging_locked (self, List[TeeStream] to_flush)

None	_flush_streams (self, List[TeeStream] to_flush)

Protected Attributes
RLock	_file_lock = RLock()

CONST.FileStreamInstances	_file_stream_instances = CONST.FileStreamInstances()

bool	_atexit_registered = False

list	_registered_flushers = []

Detailed Description

High-level coordinator that installs `TeeStream` wrappers.

Responsibilities:
- Validate and create the target log folder.
- Configure a `FileInstance` with encoding, prefix and rotation policy.
- Replace `sys.stdout` and `sys.stderr` with `TeeStream` instances.

Definition at line 56 of file rotary_logger_cls.py.

Constructor & Destructor Documentation

◆ init()

None rotary_logger.rotary_logger_cls.RotaryLogger.__init__	(		self,
		bool	log_to_file = CONST.LOG_TO_FILE_ENV,
		bool	override = False,
		str	raw_log_folder = CONST.RAW_LOG_FOLDER_ENV,
		Path	default_log_folder = CONST.DEFAULT_LOG_FOLDER,
		int	default_max_filesize = CONST.DEFAULT_LOG_MAX_FILE_SIZE,
		bool	merge_streams = True,
		*	,
		str	encoding = CONST.DEFAULT_ENCODING,
		bool	merge_stdin = False,
		bool	capture_stdin = False,
		bool	capture_stdout = True,
		bool	capture_stderr = True,
		bool	prefix_in_stream = True,
		bool	prefix_out_stream = True,
		bool	prefix_err_stream = True,
		bool	log_function_calls_stdin = False,
		bool	log_function_calls_stdout = False,
		bool	log_function_calls_stderr = False,
		bool	program_log = False,
		bool	program_debug_log = False,
		bool	suppress_program_warning_logs = False,
		bool	suppress_program_error_logs = False )

Initialise a new RotaryLogger.

Does not start logging; call start_logging() to install TeeStream
wrappers and begin mirroring output.

Arguments:
    log_to_file (bool): Whether file logging is enabled. Default: CONST.LOG_TO_FILE_ENV
    override (bool): Whether existing log files may be overwritten. Default: False
    raw_log_folder (str): Raw path string for the log folder. Default: CONST.RAW_LOG_FOLDER_ENV
    default_log_folder (Path): Fallback log folder path. Default: CONST.DEFAULT_LOG_FOLDER
    default_max_filesize (int): Maximum log file size in MB before rotation. Default: CONST.DEFAULT_LOG_MAX_FILE_SIZE
    merge_streams (bool): Whether stdout and stderr share a single log file. Default: True

Keyword Arguments:
    encoding (str): File encoding for log files. Default: CONST.DEFAULT_ENCODING
    merge_stdin (bool): Whether stdin is merged into the shared log file. Default: False
    capture_stdin (bool): Whether stdin is wrapped with a TeeStream. Default: False
    capture_stdout (bool): Whether stdout is wrapped with a TeeStream. Default: True
    capture_stderr (bool): Whether stderr is wrapped with a TeeStream. Default: True
    prefix_in_stream (bool): Whether stdin entries are prefixed. Default: True
    prefix_out_stream (bool): Whether stdout entries are prefixed. Default: True
    prefix_err_stream (bool): Whether stderr entries are prefixed. Default: True
    log_function_calls_stdin (bool): Whether TeeStream function calls on stdin are logged. Default: False
    log_function_calls_stdout (bool): Whether TeeStream function calls on stdout are logged. Default: False
    log_function_calls_stderr (bool): Whether TeeStream function calls on stderr are logged. Default: False
    program_log (bool): Whether to let the module (rotary_logger) output status logs about what it is doing. Default: False
    program_debug_log (bool): Whether to let the module (rotary_logger) output debug logs. Default: False
    suppress_program_warning_logs (bool): Whether to prevent the module (rotary_logger) from outputing warnings (ex: initialising an already initialised stream). Default: False
    suppress_program_error_logs (bool): Whether to prevent the module (rotary_logger) from outputing error (ex: a broken pipe). Default: False

Definition at line 65 of file rotary_logger_cls.py.

◆ del()

None rotary_logger.rotary_logger_cls.RotaryLogger.__del__ ( self )

Best-effort cleanup on object deletion.

Calls stop_logging() to restore original streams. Errors are not
raised since __del__ may run during interpreter shutdown.

Definition at line 172 of file rotary_logger_cls.py.

Member Function Documentation

◆ call()

None rotary_logger.rotary_logger_cls.RotaryLogger.__call__	(		self,
		*Any	args,
		**Any	kwds )

Allow the instance to be called as a function to start logging.

Calling the instance is equivalent to calling start_logging() and
is provided for compact initialisation patterns.

Arguments:
    *args (Any): Ignored positional arguments.
    **kwds (Any): Ignored keyword arguments.

Definition at line 180 of file rotary_logger_cls.py.

◆ _flush_streams()

None rotary_logger.rotary_logger_cls.RotaryLogger._flush_streams	(		self,
		List[TeeStream]	to_flush )

protected

Flush a list of TeeStream instances, suppressing expected I/O errors.

Iterates over `to_flush` and calls `flush()` on each stream. `OSError`
and `ValueError` (e.g. broken pipe, closed file descriptor) are caught
and silently ignored; all other exceptions propagate.

Arguments:
    to_flush (List[TeeStream]): Streams to flush.

Definition at line 740 of file rotary_logger_cls.py.

◆ _get_user_max_file_size()

int rotary_logger.rotary_logger_cls.RotaryLogger._get_user_max_file_size ( self )

protected

Return the maximum log file size from the environment or the current default.

Reads the `LOG_MAX_SIZE` environment variable and coerces it to an
integer. Falls back to the value stored in `file_data` if the variable
is absent or non-numeric.

Returns:
    The resolved maximum log file size in bytes (as stored by `FileInstance`).

Definition at line 193 of file rotary_logger_cls.py.

◆ _handle_stream_assignments()

None rotary_logger.rotary_logger_cls.RotaryLogger._handle_stream_assignments	(		self,
		Path	log_folder )

protected

Create `FileInstance` objects and store them in `self._file_stream_instances`.

Reads the current configuration snapshot from `self.file_data` (outside the
lock) and constructs either a single shared `FileInstance` (when `merged` is True)
or three separate per-stream instances for stdin, stdout, and stderr.

When merged, stdout and stderr share the same descriptor. stdin is also merged
into that file when `merge_stdin` is True; otherwise its own unmerged instance
is created. Merged/unmerged state is recorded in
`self._file_stream_instances.merged_streams`.

Arguments:
    log_folder (Path): The validated, writable root folder for log files.

Definition at line 319 of file rotary_logger_cls.py.

◆ _pause_logging_locked()

None rotary_logger.rotary_logger_cls.RotaryLogger._pause_logging_locked	(		self,
		List[TeeStream]	to_flush )

protected

Replace TeeStream wrappers with the original standard streams.

Must be called while `self._file_lock` is already held. Sets
`self.paused` to True and reassigns `sys.stdout`, `sys.stderr`,
and `sys.stdin` back to their original (pre-TeeStream) counterparts.
Each stream that is uninstalled is appended to `to_flush` so the
caller can flush buffered data after releasing the lock.

Arguments:
    to_flush (List[TeeStream]): Accumulator list; streams to flush after the lock is released.

Definition at line 697 of file rotary_logger_cls.py.

◆ _resolve_log_folder()

Path rotary_logger.rotary_logger_cls.RotaryLogger._resolve_log_folder	(		self,
		Optional[Path]	log_folder )

protected

Resolve and verify the final log folder to use.

Centralises the logic of falling back to the configured default and
delegates validation to _verify_user_log_path().

Arguments:
    log_folder (Optional[Path]): Requested log folder, or None to use the default.

Returns:
    The validated, writable, resolved log folder path.

Definition at line 302 of file rotary_logger_cls.py.

◆ _resume_logging_locked()

None rotary_logger.rotary_logger_cls.RotaryLogger._resume_logging_locked	(		self,
		List[TeeStream]	to_flush )

protected

Restore TeeStream wrappers on sys.stdin/stdout/stderr.

Must be called while `self._file_lock` is already held. Sets
`self.paused` to False and reassigns `sys.stdout`, `sys.stderr`,
and `sys.stdin` to their respective TeeStream instances. Each
stream that is reinstalled is appended to `to_flush` so the
caller can flush them after releasing the lock.

Arguments:
    to_flush (List[TeeStream]): Accumulator list; streams to flush after the lock is released.

Definition at line 662 of file rotary_logger_cls.py.

◆ _verify_user_log_path()

Path rotary_logger.rotary_logger_cls.RotaryLogger._verify_user_log_path	(		self,
		Path	raw_log_folder = CONST.DEFAULT_LOG_FOLDER )

protected

Validate, resolve and ensure writability of the requested log folder.

Resolves relative paths against the package directory, appends the
standard base-folder name when missing, and performs a write-test.
Falls back to the default log folder on any validation failure.

Keyword Arguments:
    raw_log_folder (Path): Candidate log folder path. Default: CONST.DEFAULT_LOG_FOLDER

Raises:
    RuntimeError: If both the requested path and the default fallback are not writable.

Returns:
    The validated, writable, resolved log folder path.

Definition at line 223 of file rotary_logger_cls.py.

◆ is_logging()

bool rotary_logger.rotary_logger_cls.RotaryLogger.is_logging ( self )

Return True if logging is currently active (not paused).

Checks whether any TeeStream is installed and the logger is not
marked as paused. Safe to call concurrently.

Returns:
    True if at least one TeeStream is installed and the logger is not paused.

Definition at line 860 of file rotary_logger_cls.py.

◆ is_redirected()

bool rotary_logger.rotary_logger_cls.RotaryLogger.is_redirected	(		self,
		CONST.StdMode	stream )

Return whether the given standard stream is currently redirected.

Lightweight query; safe to call concurrently.

Arguments:
    stream (CONST.StdMode): One of CONST.StdMode.STDOUT, STDERR, or STDIN.

Returns:
    True if the corresponding stream has a TeeStream installed, False otherwise.

Definition at line 834 of file rotary_logger_cls.py.

◆ pause_logging()

bool rotary_logger.rotary_logger_cls.RotaryLogger.pause_logging	(		self,
		*	,
		bool	toggle = True )

Toggle the logger pause state.

When the logger is paused the TeeStream objects are uninstalled and
the original streams restored. When called again the TeeStream objects
are reinstalled. sys.* assignments are performed while holding the
internal lock; flushing is done afterwards to keep critical sections
short.

Keyword Arguments:
    toggle (bool): When True and the logger is currently running, pause it; when True and already paused, resume it. When False, always pause. Default: True

Returns:
    The new paused state (True when now paused, False when now resumed).

Definition at line 768 of file rotary_logger_cls.py.

◆ resume_logging()

bool rotary_logger.rotary_logger_cls.RotaryLogger.resume_logging	(		self,
		*	,
		bool	toggle = False )

Explicitly resume logging (idempotent).

Equivalent to calling pause_logging() while paused, but provided as
a convenience. sys.* assignments are made under the internal lock;
flushing is done afterwards.

Keyword Arguments:
    toggle (bool): When True and the logger is not paused, pause it instead of resuming. When False, always resume. Default: False

Returns:
    The paused state after the call (False when logging was resumed, True when toggled into pause).

Definition at line 803 of file rotary_logger_cls.py.

◆ start_logging()

None rotary_logger.rotary_logger_cls.RotaryLogger.start_logging	(		self,
		*	,
		Optional[Path]	log_folder = None,
		Optional[int]	max_filesize = None,
		Optional[bool]	merged = None,
		bool	log_to_file = True,
		Optional[bool]	merge_stdin = None,
		bool	skip_redirect_check_stdin = False,
		bool	skip_redirect_check_stdout = False,
		bool	skip_redirect_check_stderr = False )

Start capturing stdout and stderr and configure file output.

Installs TeeStream wrappers for sys.stdout and sys.stderr so output
continues to appear on the terminal while being mirrored to rotating
files on disk. Configuration snapshots are taken under the internal
lock; filesystem operations (mkdir, write-test) are performed outside
it to keep critical sections short. The sys.* assignments are made
while holding the lock to keep the replacement atomic.

Keyword Arguments:
    log_folder (Optional[Path]): Base folder to write logs; falls back to configured defaults. Default: None
    max_filesize (Optional[int]): Override for the rotation size in MB. Default: None
    merged (Optional[bool]): Whether to merge stdout and stderr into one file. Default: None
    log_to_file (bool): Whether file writes are enabled. Default: True
    merge_stdin (Optional[bool]): Whether to merge stdin into the shared log file. Default: None
    skip_redirect_check_stdin (bool, optional):  Skip the existing redirection check for stdin, allowing multiple logger instances to redirect the same stream (legacy behavior). Default: False
    skip_redirect_check_stdout (bool, optional): Skip the existing redirection check for stdout, allowing multiple logger instances to redirect the same stream (legacy behavior). Default: False,
    skip_redirect_check_stderr (bool, optional): Skip the existing redirection check for stderr, allowing multiple logger instances to redirect the same stream (legacy behavior). Default: False,

Definition at line 431 of file rotary_logger_cls.py.

◆ stop_logging()

None rotary_logger.rotary_logger_cls.RotaryLogger.stop_logging ( self )

Stop logging and restore the original standard streams.

Restores sys.stdout, sys.stderr, and sys.stdin to their original
values, attempts to unregister any atexit flush handlers registered
by start_logging(), and flushes remaining buffers. Stream replacement
and atexit unregistration are done under the internal lock; flushing
is performed afterwards.

Definition at line 880 of file rotary_logger_cls.py.

Field Documentation

◆ _atexit_registered

bool rotary_logger.rotary_logger_cls.RotaryLogger._atexit_registered = False

protected

Definition at line 155 of file rotary_logger_cls.py.

◆ _file_lock [1/5]

rotary_logger.rotary_logger_cls.RotaryLogger._file_lock = RLock()

protected

Definition at line 121 of file rotary_logger_cls.py.

◆ _file_lock [2/5]

Path rotary_logger.rotary_logger_cls.RotaryLogger._file_lock = self.default_log_folder

Definition at line 314 of file rotary_logger_cls.py.

◆ _file_lock [3/5]

FileInstance rotary_logger.rotary_logger_cls.RotaryLogger._file_lock = self.file_data.get_override()

Definition at line 334 of file rotary_logger_cls.py.

◆ _file_lock [4/5]

Optional[TeeStream] rotary_logger.rotary_logger_cls.RotaryLogger._file_lock = self.stderr_stream

Definition at line 848 of file rotary_logger_cls.py.

◆ _file_lock [5/5]

tuple rotary_logger.rotary_logger_cls.RotaryLogger._file_lock

Initial value:

=  (
                self.stdout_stream is not None
            ) or (
                self.stderr_stream is not None
            ) or (
                self.stdin_stream is not None
            )

Definition at line 869 of file rotary_logger_cls.py.

◆ _file_stream_instances

CONST.FileStreamInstances rotary_logger.rotary_logger_cls.RotaryLogger._file_stream_instances = CONST.FileStreamInstances()

protected

Definition at line 147 of file rotary_logger_cls.py.

◆ _registered_flushers

list rotary_logger.rotary_logger_cls.RotaryLogger._registered_flushers = []

protected

Definition at line 156 of file rotary_logger_cls.py.

◆ capture_stderr

bool rotary_logger.rotary_logger_cls.RotaryLogger.capture_stderr = capture_stderr

Definition at line 141 of file rotary_logger_cls.py.

◆ capture_stdin

bool rotary_logger.rotary_logger_cls.RotaryLogger.capture_stdin = capture_stdin

Definition at line 139 of file rotary_logger_cls.py.

◆ capture_stdout

bool rotary_logger.rotary_logger_cls.RotaryLogger.capture_stdout = capture_stdout

Definition at line 140 of file rotary_logger_cls.py.

◆ default_log_folder

Path rotary_logger.rotary_logger_cls.RotaryLogger.default_log_folder = default_log_folder

Definition at line 124 of file rotary_logger_cls.py.

◆ default_max_filesize

int rotary_logger.rotary_logger_cls.RotaryLogger.default_max_filesize = default_max_filesize

Definition at line 125 of file rotary_logger_cls.py.

◆ file_data

FileInstance rotary_logger.rotary_logger_cls.RotaryLogger.file_data = FileInstance(None)

Definition at line 132 of file rotary_logger_cls.py.

◆ log_function_calls_stderr

rotary_logger.rotary_logger_cls.RotaryLogger.log_function_calls_stderr = log_function_calls_stderr

Definition at line 145 of file rotary_logger_cls.py.

◆ log_function_calls_stdin

rotary_logger.rotary_logger_cls.RotaryLogger.log_function_calls_stdin = log_function_calls_stdin

Definition at line 143 of file rotary_logger_cls.py.

◆ log_function_calls_stdout

rotary_logger.rotary_logger_cls.RotaryLogger.log_function_calls_stdout = log_function_calls_stdout

Definition at line 144 of file rotary_logger_cls.py.

◆ log_to_file [1/2]

bool rotary_logger.rotary_logger_cls.RotaryLogger.log_to_file = log_to_file

Definition at line 122 of file rotary_logger_cls.py.

◆ log_to_file [2/2]

Path rotary_logger.rotary_logger_cls.RotaryLogger.log_to_file = self._verify_user_log_path(_raw_folder)

Definition at line 493 of file rotary_logger_cls.py.

◆ paused

bool rotary_logger.rotary_logger_cls.RotaryLogger.paused = False

Definition at line 153 of file rotary_logger_cls.py.

◆ prefix

rotary_logger.rotary_logger_cls.RotaryLogger.prefix = CONST.Prefix()

Definition at line 127 of file rotary_logger_cls.py.

◆ program_debug_log

rotary_logger.rotary_logger_cls.RotaryLogger.program_debug_log = program_debug_log

Definition at line 159 of file rotary_logger_cls.py.

◆ program_log

rotary_logger.rotary_logger_cls.RotaryLogger.program_log = program_log

Definition at line 158 of file rotary_logger_cls.py.

◆ raw_log_folder [1/2]

Path rotary_logger.rotary_logger_cls.RotaryLogger.raw_log_folder = Path(raw_log_folder)

Definition at line 123 of file rotary_logger_cls.py.

◆ raw_log_folder [2/2]

str rotary_logger.rotary_logger_cls.RotaryLogger.raw_log_folder = self.default_log_folder

Definition at line 473 of file rotary_logger_cls.py.

◆ rogger

Rogger rotary_logger.rotary_logger_cls.RotaryLogger.rogger = RI

Definition at line 162 of file rotary_logger_cls.py.

◆ stderr_stream

Optional[TeeStream] rotary_logger.rotary_logger_cls.RotaryLogger.stderr_stream = None

Definition at line 150 of file rotary_logger_cls.py.

◆ stdin_stream

rotary_logger.rotary_logger_cls.RotaryLogger.stdin_stream = None

Definition at line 151 of file rotary_logger_cls.py.

◆ stdout_stream

Optional[TeeStream] rotary_logger.rotary_logger_cls.RotaryLogger.stdout_stream = None

Definition at line 149 of file rotary_logger_cls.py.

◆ suppress_program_error_logs

rotary_logger.rotary_logger_cls.RotaryLogger.suppress_program_error_logs = suppress_program_error_logs

Definition at line 161 of file rotary_logger_cls.py.

◆ suppress_program_warning_logs

rotary_logger.rotary_logger_cls.RotaryLogger.suppress_program_warning_logs = suppress_program_warning_logs

Definition at line 160 of file rotary_logger_cls.py.

The documentation for this class was generated from the following file:

rotary_logger/rotary_logger_cls.py

Public Member Functions

Data Fields

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ __init__()

◆ __del__()

Member Function Documentation

◆ __call__()

◆ _flush_streams()

◆ _get_user_max_file_size()

◆ _handle_stream_assignments()

◆ _pause_logging_locked()

◆ _resolve_log_folder()

◆ _resume_logging_locked()

◆ _verify_user_log_path()

◆ is_logging()

◆ is_redirected()

◆ pause_logging()

◆ resume_logging()

◆ start_logging()

◆ stop_logging()

Field Documentation

◆ _atexit_registered

◆ _file_lock [1/5]

◆ _file_lock [2/5]

◆ _file_lock [3/5]

◆ _file_lock [4/5]

◆ _file_lock [5/5]

◆ _file_stream_instances

◆ _registered_flushers

◆ capture_stderr

◆ capture_stdin

◆ capture_stdout

◆ default_log_folder

◆ default_max_filesize

◆ file_data

◆ log_function_calls_stderr

◆ log_function_calls_stdin

◆ log_function_calls_stdout

◆ log_to_file [1/2]

◆ log_to_file [2/2]

◆ paused

◆ prefix

◆ program_debug_log

◆ program_log

◆ raw_log_folder [1/2]

◆ raw_log_folder [2/2]

◆ rogger

◆ stderr_stream

◆ stdin_stream

◆ stdout_stream

◆ suppress_program_error_logs

◆ suppress_program_warning_logs

◆ init()

◆ del()

◆ call()