log_utils

Logging utilities for managing log output and tracking execution time in the okcourse package.

This module provides functions for setting up logging to both the console and optionally to a file, retrieving package versions, and a context manager for tracking execution time for profiling purposes.

Functions:

Name	Description
`get_logger`	Enable logging to the console and optionally to a file for the specified source.
`get_top_level_version`	Retrieve the version of the specified top-level package.
`time_tracker`	A `contextmanager` that tracks elapsed time and stores it in the specified attribute of the target object.

get_logger

get_logger(
    source_name: str = "okcourse",
    level: int = INFO,
    file_path: Path | None = None,
) -> Logger

Enable logging to the console and optionally to a file for the specified source.

You typically will get the name of the source module or function by calling __name__ in the source.

Parameters:

Name	Type	Description	Default
`source_name`	`str`	The source (module, method, etc.) that will pass log event messages to this logger.	`'okcourse'`
`level`	`int`	The logging level to set for the logger.	`INFO`
`file_path`	`Path \| None`	The path to a file where logs will be written. If not provided, logs are written only to the console.	`None`

Examples:

Get the logger for a module and then set up a couple log events:

# This is the do_things.py module
from log_utils import get_logger

# Get the private logger instance for the do_things module
_log = get_logger(__name__)

# Then use the logger elsewhere in the module to log events
def do_a_thing():
    _log.info("About to do a thing...")
    thing.doer.do(thing)
    _log.info("Did the thing.")

get_top_level_version

get_top_level_version(package_name: str) -> str

Retrieve the version of the specified top-level package.

Parameters:

Name	Type	Description	Default
`package_name`	`str`	The name of the top-level package.	required

Returns:

Name	Type	Description
`str`	`str`	The version of the package.

Raises:

Type	Description
`PackageNotFoundError`	If the package is not found.

time_tracker

time_tracker(target_object: object, attribute_name: str)

A contextmanager that tracks elapsed time and stores it in the specified attribute of the target object.

Wrap your long-running operation with the time_tracker context manager and pass it the object and the name of the attribute on the object you want to store the elapsed time in.

Parameters:

Name	Type	Description	Default
`target_object`	`object`	The object where the elapsed time should be recorded.	required
`attribute_name`	`str`	The name of the attribute on the given target object where the elapsed time should be stored.	required

Examples:

Record time elapsed generating a course's outline in the course's CourseGenerationInfo:

async def generate_outline(self, course: Course) -> Course:
    with time_tracker(course.generation_info, "outline_generation_elapsed"):
        # Long-running operation here
    return course