Packages¶

# mypackage/core/models.py
__all__ = [
    "BaseModel",
    "Config",
    "ValidationError",
]

class BaseModel: ...
class Config: ...
class ValidationError(Exception): ...
class _InternalHelper: ...  # Not in __all__, private

# mypackage/__init__.py
"""MyPackage - A brief description."""

from mypackage.core.models import BaseModel, Config, ValidationError
from mypackage.core.processor import process

__all__ = [
    # Models
    "BaseModel",
    "Config",
    "ValidationError",
    # Functions
    "process",
]

__version__ = "1.0.0"

import warnings

def old_function():
    """Deprecated: Use new_function instead."""
    warnings.warn(
        "old_function is deprecated, use new_function instead",
        DeprecationWarning,
        stacklevel=2,
    )
    return new_function()

# mypackage/core/processor.py
import logging

logger = logging.getLogger(__name__)

def process(data: str) -> str:
    logger.debug("Processing data: %s", data)
    # ... logic
    logger.info("Processing complete")
    return result

# mypackage/__init__.py
import logging
logging.getLogger(__name__).addHandler(logging.NullHandler())

# mypackage/cli.py
try:
    import typer
    from rich.console import Console
except ImportError:
    raise ImportError(
        "CLI dependencies not installed. "
        "Install with: pip install mypackage[cli]"
    )

from mypackage.core.processor import process

app = typer.Typer()
console = Console()

@app.command()
def run(input_file: str):
    """Process the input file."""
    result = process(input_file)
    console.print(result)

# noxfile.py
import nox

@nox.session(python=["3.11", "3.12", "3.13"])
def tests(session):
    session.install(".[dev]")
    session.run("pytest", "tests/", "-v")

@nox.session(python="3.12")
def lint(session):
    session.install("ruff")
    session.run("ruff", "check", "src/")

@nox.session(python="3.12")
def typecheck(session):
    session.install(".[dev]")
    session.run("pyright", "src/")

# mypackage/backends/__init__.py
from typing import TYPE_CHECKING

if TYPE_CHECKING:
    import pandas as pd
    import polars as pl

# Cache imported modules to avoid repeated ImportError checking
# Note: Python's import system already caches modules after first import,
# but this pattern also caches the ImportError check itself, which is useful
# when functions are called thousands of times in tight loops.
_pandas_module = None
_polars_module = None


def _get_pandas():
    """Get pandas module with caching.

    Performance note:
    - Primarily caches the ImportError check/handling
    - Modest benefit (~1-5μs per call) but useful in high-frequency scenarios
    - Main value is cleaner separation of import logic from business logic
    """
    global _pandas_module
    if _pandas_module is None:
        try:
            import pandas as pd
            _pandas_module = pd
        except ImportError:
            raise ImportError("Install with: pip install mypackage[pandas]")
    return _pandas_module


def _get_polars():
    """Get polars module with caching.

    Performance note:
    - Primarily caches the ImportError check/handling
    """
    global _polars_module
    if _polars_module is None:
        try:
            import polars as pl
            _polars_module = pl
        except ImportError:
            raise ImportError("Install with: pip install mypackage[polars]")
    return _polars_module


def load_with_pandas(path: str) -> "pd.DataFrame":
    """Load CSV with pandas, using cached module import."""
    pd = _get_pandas()
    return pd.read_csv(path)


def load_with_polars(path: str) -> "pl.DataFrame":
    """Load CSV with polars, using cached module import."""
    pl = _get_polars()
    return pl.read_csv(path)

# mypackage/utils.py
# Good: Heavy imports only when function is called
def process_with_pandas(data: str) -> dict:
    """Process data with pandas (lazy import)."""
    import pandas as pd  # Only imported if this function is used
    import numpy as np
    df = pd.DataFrame({"data": [data]})
    return df.to_dict()

# Bad: Heavy imports at module level
# import pandas as pd  # Imported even if never used
# import numpy as np

from functools import lru_cache
import hashlib

@lru_cache(maxsize=128)
def compute_expensive_hash(data: str) -> str:
    """Compute hash with caching.

    Performance: Repeated calls with same input return cached result.
    Useful for frequently called functions with repeated inputs.
    """
    # Simulate expensive operation
    for _ in range(1000):
        data = hashlib.sha256(data.encode()).hexdigest()
    return data

# First call: ~1ms
# Subsequent calls with same input: ~1μs (1000x faster)
result = compute_expensive_hash("same-input")