stouputils.ctx.log_to_file module#

ROUTING_LOCK: allocate_lock = <unlocked _thread.lock object>[source]#

Keeps two threads opening or closing a LogToFile at once from each putting their own TeeMultiOutput in place.

class LogToFile(
path: str,
mode: str = 'w',
encoding: str = 'utf-8',
tee_stdout: bool = True,
tee_stderr: bool = True,
strip_colors: bool = False,
ignore_lineup: bool = True,
restore_on_exit: bool = True,
capture_fd: bool = False,
)[source]#

Bases: AbstractBothContextManager[LogToFile]

Context manager to log to a file.

This context manager allows you to temporarily log output to a file while still printing normally.

Every LogToFile writes through the same TeeMultiOutput, put in place by the first one and taken away with the last one, so they nest and close in any order. One opened in the main thread receives the output of every thread, one opened in another thread only the output of that thread.

Parameters:

  • path – Path to the log file

  • mode – Mode to open the file in (default: “w”)

  • encoding – Encoding to use for the file (default: “utf-8”)

  • tee_stdout – Whether to redirect stdout to the file (default: True)

  • tee_stderr – Whether to redirect stderr to the file (default: True)

  • ignore_lineup – Whether the file receives what a terminal ends up showing (default: True): a progress bar once in its final state, and no line the cursor moves back to

  • restore_on_exit – Whether the last LogToFile to close gives stdout/stderr back (default: True)

  • capture_fd – Whether the file also receives what bypasses sys.stdout (default: False): C extensions, os.system, uncaptured child processes. Skipped with a warning where unsupported, see FdCapture.

> import stouputils as stp
> with stp.LogToFile("output.log"):
>     stp.info("This will be logged to output.log and printed normally")
>     print("This will also be logged")

> with stp.LogToFile("output.log") as log_ctx:
>     stp.warning("This will be logged to output.log and printed normally")
>     log_ctx.change_file("new_file.log")
>     print("This will be logged to new_file.log")
path: str[source]#

Attribute remembering path to the log file

mode: str[source]#

Attribute remembering mode to open the file in

encoding: str[source]#

Attribute remembering encoding to use for the file

tee_stdout: bool[source]#

Whether to redirect stdout to the file

tee_stderr: bool[source]#

Whether to redirect stderr to the file

strip_colors: bool[source]#

Whether to strip ANSI color codes from output sent to non-stdout/stderr files

ignore_lineup: bool[source]#

Whether the file receives what a terminal ends up showing

restore_on_exit: bool[source]#

Whether the last LogToFile to close gives stdout/stderr back

_abc_impl = <_abc._abc_data object>[source]#
file: IO[Any][source]#

Attribute remembering opened file

tees: dict[str, TeeMultiOutput][source]#

The stream objects holding the file, by the name of the sys attribute they stand in for

capture_fd: bool[source]#

Whether the file also receives what bypasses sys.stdout

fd_capture: FdCapture | None[source]#

Capture of the descriptors while it runs, through which the file then receives everything

change_file(new_path: str) → None[source]#

Change the log file to a new path.

Parameters:

new_path – New path to the log file

static common(
logs_folder: str,
filepath: str,
func: CallableAny,
init_kwargs: dict[str, Any] | None = None,
*args: Any,
**kwargs: Any,
) → Any[source]#

Common code used at the beginning of a program to launch main function

Parameters:

  • logs_folder – Folder to store logs in

  • filepath – Path to the main function

  • func – Main function to launch

  • init_kwargs – Keyword arguments to pass to LogToFile constructor

  • *args – Arguments to pass to the main function

  • **kwargs – Keyword arguments to pass to the main function

Returns:

Return value of the main function

>>> if __name__ == "__main__":
...     LogToFile.common(f"{ROOT}/logs", __file__, main, init_kwargs={"strip_colors": True})