Skip to content

Logger

logger

Logging configuration and utilities for pyballistic library.

This module provides a centralized logging system for the pyballistic library, including both console and optional file logging capabilities. The logger is configured with appropriate formatters and can be dynamically adjusted for different logging needs.

The module exposes a pre-configured logger instance and utility functions for managing file-based logging. By default, only console logging is enabled with INFO level, but file logging can be enabled as needed for debugging or detailed analysis.

Global Variables
  • logger: Pre-configured logger instance for the library.
  • file_handler: Global file handler reference (None when file logging disabled).

Functions:

Name Description
enable_file_logging

Enable logging to a file with DEBUG level.
disable_file_logging

Disable file logging and clean up resources.

Examples:

Basic logging usage: 

from pyballistic.logger import logger

logger.info("Ballistic calculation started")
logger.warning("Trajectory calculation ended before requested distance")
logger.error("Unable to find angle to hit target")

Enable file logging for debugging: 

from pyballistic.logger import enable_file_logging, disable_file_logging

# Enable detailed logging to file
enable_file_logging("ballistics_debug.log")

# Perform calculations with detailed logging
# ... ballistic calculations ...

# Clean up file logging
disable_file_logging()

Note

The logger name 'py_balcalc' is used for historical compatibility. All log messages from the library components will be routed through this logger.

Attributes:

Name Type Description
__all__
formatter
console_handler
logger Logger
file_handler Optional[FileHandler]

Attributes

__all__ module-attribute 
__all__ = (
    "logger",
    "enable_file_logging",
    "disable_file_logging",
)
formatter module-attribute 
formatter = Formatter('%(levelname)s:%(name)s:%(message)s')
console_handler module-attribute 
console_handler = StreamHandler()
logger module-attribute 
logger: Logger = getLogger('py_balcalc')
file_handler module-attribute 
file_handler: Optional[FileHandler] = None

Functions

enable_file_logging 
enable_file_logging(filename: str = 'debug.log') -> None

Enable logging to a file with DEBUG level output.

This function configures file-based logging, replacing any existing file handler. File logging captures all DEBUG level messages and above with timestamp information, providing detailed logging for debugging and analysis purposes.

Parameters:

Name Type Description Default
filename str

Name of the log file to create. Defaults to "debug.log". The file will be created in the current working directory unless an absolute path is provided.

 'debug.log'
Note

If file logging is already enabled, the existing file handler will be removed and replaced with a new one using the specified filename. The file will be opened in append mode, so existing content is preserved.

Examples:

from pyballistic.logger import enable_file_logging, logger

# Enable detailed file logging
enable_file_logging("trajectory_analysis.log")

# All subsequent log messages will be written to file
logger.debug("Detailed calculation step information")
logger.info("Calculation completed successfully")
Source code in pyballistic/logger.py 
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
def enable_file_logging(filename: str = "debug.log") -> None:
    """Enable logging to a file with DEBUG level output.

    This function configures file-based logging, replacing any existing file handler.
    File logging captures all DEBUG level messages and above with timestamp information,
    providing detailed logging for debugging and analysis purposes.

    Args:
        filename: Name of the log file to create. Defaults to "debug.log".
                 The file will be created in the current working directory
                 unless an absolute path is provided.

    Note:
        If file logging is already enabled, the existing file handler will be
        removed and replaced with a new one using the specified filename.
        The file will be opened in append mode, so existing content is preserved.

    Examples:
        ```python
        from pyballistic.logger import enable_file_logging, logger

        # Enable detailed file logging
        enable_file_logging("trajectory_analysis.log")

        # All subsequent log messages will be written to file
        logger.debug("Detailed calculation step information")
        logger.info("Calculation completed successfully")
        ```
    """
    global file_handler
    # Remove the existing file handler if it exists
    if file_handler is not None:
        disable_file_logging()

    # Add a new file handler
    file_handler = logging.FileHandler(filename)
    file_handler.setLevel(logging.DEBUG)  # Log everything to the file
    file_formatter = logging.Formatter("%(asctime)s:%(levelname)s:%(message)s")
    file_handler.setFormatter(file_formatter)
    logger.addHandler(file_handler)
disable_file_logging 
disable_file_logging() -> None

Disable file logging and clean up resources.

This function removes the file handler from the logger and properly closes the file handle, ensuring no resource leaks. After calling this function, only console logging will remain active.

Note

If no file logging is currently enabled, this function has no effect. It's safe to call this function multiple times or when file logging is already disabled.

Examples:

from pyballistic.logger import disable_file_logging

# Clean up file logging when done with detailed analysis
disable_file_logging()

# Only console logging remains active
Source code in pyballistic/logger.py 
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
def disable_file_logging() -> None:
    """Disable file logging and clean up resources.

    This function removes the file handler from the logger and properly closes the file handle,
    ensuring no resource leaks. After calling this function, only console logging will remain active.

    Note:
        If no file logging is currently enabled, this function has no effect.
        It's safe to call this function multiple times or when file logging is already disabled.

    Examples:
        ```python
        from pyballistic.logger import disable_file_logging

        # Clean up file logging when done with detailed analysis
        disable_file_logging()

        # Only console logging remains active
        ```
    """
    global file_handler
    if file_handler is not None:
        logger.removeHandler(file_handler)
        file_handler.close()
        file_handler = None