API Reference

Auto-generated code documentation.

analytics_project

demo_module_basics

Demonstrate Python basics for professional analytics.

This module demonstrates fundamental Python concepts essential for data analysts, including imports, variables, functions, and function calls.

Module Information

• Filename: demo_module_basics.py
• Module: demo_module_basics
• Location: src/analytics_project/

Key Concepts

• Module imports and code organization
• Variable declaration and scope
• Function definition (reusable logic)
• Function invocation and returns

Professional Applications

• Building maintainable analytics pipelines
• Creating reusable analysis functions
• Organizing code for team collaboration
• Setting up logging for production debugging

demo_basics

demo_basics() -> None

Demonstrate Python basics.

Source code in src/analytics_project/demo_module_basics.py

def demo_basics() -> None:
    """Demonstrate Python basics."""
    logger.info("Starting demo_python() function.")
    show_naming_and_comments()
    show_variables_and_types()
    show_functions_and_fstrings()
    show_builtins_example()
    show_truths()
    logger.info("Experiment with this demo script to learn the basics quickly.")
    logger.info("Exiting demo_python() function.")

main

main() -> None

Test demo locally.

Source code in src/analytics_project/demo_module_basics.py

def main() -> None:
    """Test demo locally."""
    try:
        init_logger()
    except Exception as exc:
        logger.exception(f"Exception occurred during logger initialization: {exc}")
    demo_basics()

main

Entry point for professional analytics project execution.

This module serves as the orchestrator, demonstrating how professional Python projects integrate multiple modules into a cohesive application.

Module Information

• Filename: main.py
• Module: main
• Location: src/analytics_project/

main

main() -> int

Demonstrate a complete Python project structure.

This function coordinates multiple demo modules to illustrate how professional Python projects integrate and run as a pipeline.

Returns:

Name	Type	Description
int	int	Exit status code (0 for success, 1 for failure) — standard practice in professional Python projects.

Source code in src/analytics_project/main.py

def main() -> int:
    """Demonstrate a complete Python project structure.

    This function coordinates multiple demo modules to illustrate
    how professional Python projects integrate and run as a pipeline.

    Returns:
        int: Exit status code (0 for success, 1 for failure)
             — standard practice in professional Python projects.
    """
    # Initialize logging for consistent console + file output
    init_logger()
    logger.info("Starting main analytics demo.")

    try:
        # Sequentially run each module to simulate an ETL-like process
        demo_basics()  # Basic operations and data handling
        logger.info("Demo complete.")
        return 0  # Returning 0 indicates success in professional scripts

    except Exception as e:
        # Application-level exception handling (never let a crash go silent)
        logger.error(f"Error executing demo demo: {e}")
        return 1  # Non-zero exit codes signal an error to the OS or CI system

utils_logger

Provide centralized logging for professional analytics projects.

This module configures project-wide logging to track events, debug issues, and maintain audit trails during data analysis workflows.

Module Information

• Filename: utils_logger.py
• Module: utils_logger
• Location: src/analytics_project/

Key Concepts

• Centralized logging configuration
• Log levels (DEBUG, INFO, WARNING, ERROR)
• File-based log persistence
• Colorized console output with Loguru

Professional Applications

• Production debugging and troubleshooting
• Audit trails for regulatory compliance
• Performance monitoring and optimization
• Error tracking in data pipelines

get_log_file_path

get_log_file_path() -> pathlib.Path

Return the path to the active log file, or default path if not initialized.

Source code in src/analytics_project/utils_logger.py

def get_log_file_path() -> pathlib.Path:
    """Return the path to the active log file, or default path if not initialized."""
    if _log_file_path is not None:
        return _log_file_path
    # Fallback: predictable location even before init_logger() runs
    return project_root / "project.log"

init_logger

init_logger(
    level: str = 'INFO',
    *,
    log_dir: str | Path = project_root,
    log_file_name: str = 'project.log',
) -> pathlib.Path

Initialize the logger and return the log file path.

Ensures the log folder exists and configures logging to write to a file.

Parameters:

Name	Type	Description	Default
level	str	Logging level (e.g., "INFO", "DEBUG").	'INFO'
log_dir	str | Path	Directory where the log file will be written.	project_root
log_file_name	str	File name for the log file.	'project.log'

Returns:

Type	Description
Path	pathlib.Path: The resolved path to the log file.

Source code in src/analytics_project/utils_logger.py

def init_logger(
    level: str = "INFO",
    *,
    log_dir: str | pathlib.Path = project_root,
    log_file_name: str = "project.log",
) -> pathlib.Path:
    """Initialize the logger and return the log file path.

    Ensures the log folder exists and configures logging to write to a file.

    Args:
        level (str): Logging level (e.g., "INFO", "DEBUG").
        log_dir: Directory where the log file will be written.
        log_file_name: File name for the log file.

    Returns:
        pathlib.Path: The resolved path to the log file.
    """
    global _is_configured
    if _is_configured:
        # If already configured once for this process
        return pathlib.Path(log_dir) / log_file_name

    # print a visual separator before logs
    print("-----------------------")

    # Resolve and ensure log folder exists
    log_folder = pathlib.Path(log_dir).expanduser().resolve()
    log_folder.mkdir(parents=True, exist_ok=True)

    # Build log file path
    log_file = log_folder / log_file_name

    try:
        fmt = "{time:YYYY-MM-DD HH:mm}:{level:<7} AT {file}:{line}: {message}"
        # Remove any existing Loguru handlers to avoid duplicate output
        logger.remove()
        logger.add(sys.stderr, level=level, format=fmt)
        logger.add(
            log_file,
            level=level,
            enqueue=True,
            backtrace=True,
            diagnose=False,
            rotation="10 MB",
            retention="7 days",
            encoding="utf-8",
            format=fmt,
        )
        logger.info(f"Logging to file: {log_file.resolve()}")
        _is_configured = True
        _log_file_path = log_file  # cache for retrieval
    except Exception as e:
        logger.error(f"Error configuring logger to write to file: {e}")

    return log_file

log_example

log_example() -> None

Demonstrate logging behavior with example messages.

Source code in src/analytics_project/utils_logger.py

def log_example() -> None:
    """Demonstrate logging behavior with example messages."""
    logger.info("This is an example info message.")
    logger.warning("This is an example warning message.")
    logger.error("This is an example error message.")

main

main() -> None

Execute logger setup and demonstrate its usage.

Source code in src/analytics_project/utils_logger.py

def main() -> None:
    """Execute logger setup and demonstrate its usage."""
    log_file = init_logger()
    log_example()
    logger.info(f"View the log output at {log_file}")