API Reference

load_jsonc(path: Path) -> dict[str, Any] | list[Any] | None

from apathetic_utils import load_jsonc
from pathlib import Path

config = load_jsonc(Path("config.jsonc"))
# {
#   "name": "my_app",
#   "version": "1.0.0"
# }

load_toml(path: Path, *, required: bool = False) -> dict[str, Any] | None

from apathetic_utils import load_toml
from pathlib import Path

pyproject = load_toml(Path("pyproject.toml"), required=True)

normalize_path_string(raw: str) -> str

from apathetic_utils import normalize_path_string

path = normalize_path_string("src\\utils\\file.py")
# Returns: "src/utils/file.py"

path = normalize_path_string("src//utils///file.py")
# Returns: "src/utils/file.py"

has_glob_chars(s: str) -> bool

from apathetic_utils import has_glob_chars

has_glob_chars("src/**/*.py")  # True
has_glob_chars("src/file.py")  # False

get_glob_root(pattern: str) -> Path

from apathetic_utils import get_glob_root

root = get_glob_root("src/**/*.txt")
# Returns: Path("src")

root = get_glob_root("tests/unit/**/*.py")
# Returns: Path("tests/unit")

shorten_path(
    path: str | Path,
    bases: str | Path | list[str | Path]
) -> str

from apathetic_utils import shorten_path

# Single base
result = shorten_path(
    "/home/user/code/serger/src/serger/logs.py",
    "/home/user/code/serger/tests/utils/patch_everywhere.py"
)
# Returns: "src/serger/logs.py"

# Multiple bases - returns shortest
result = shorten_path(
    "/home/user/code/serger/src/logs.py",
    ["/home/user/code/serger/tests/utils/patch.py",
     "/home/user/code/serger/src"]
)
# Returns: "logs.py" (shortest: common prefix with src/)

# Returns absolute path when only root in common
result = shorten_path(
    "/var/lib/file.py",
    ["/home/user", "/tmp"]
)
# Returns: "/var/lib/file.py" (absolute path)

fnmatchcase_portable(path: str, pattern: str) -> bool

from apathetic_utils import fnmatchcase_portable

fnmatchcase_portable("src/utils/file.py", "src/**/*.py")  # True
fnmatchcase_portable("deep/nested/file.py", "**/*.py")    # True
fnmatchcase_portable("src/file.py", "src/*.py")            # True

is_excluded_raw(
    path: Path | str,
    exclude_patterns: list[str],
    root: Path | str
) -> bool

from apathetic_utils import is_excluded_raw
from pathlib import Path

patterns = ["**/__pycache__/**", "*.pyc", "tests/**"]
root = Path(".")

is_excluded_raw("src/__pycache__/file.pyc", patterns, root)  # True
is_excluded_raw("src/utils/file.py", patterns, root)         # False

detect_packages_from_files(
    file_paths: list[Path],
    package_name: str,
    *,
    source_bases: list[str] | None = None,
    _config_dir: Path | None = None
) -> tuple[set[str], list[str]]

from apathetic_utils import detect_packages_from_files
from pathlib import Path

files = [Path("src/mypkg/module.py"), Path("src/otherpkg/file.py")]
packages, parents = detect_packages_from_files(
    files,
    "mypkg",
    source_bases=["/path/to/src"]
)
# packages: {"mypkg", "otherpkg", "mypkg"} (includes configured name)
# parents: ["/path/to/src"]

find_all_packages_under_path(root_path: Path) -> set[str]

from apathetic_utils import find_all_packages_under_path
from pathlib import Path

packages = find_all_packages_under_path(Path("src"))
# Returns: {"mypkg", "otherpkg"} (all top-level packages with __init__.py)

is_ci() -> bool

from apathetic_utils import is_ci

if is_ci():
    print("Running in CI environment")
    # Adjust behavior for CI

if_ci(ci_value: T, local_value: T) -> T

from apathetic_utils import if_ci

# Different regex patterns for commit hashes
commit_pattern = if_ci(
    r"[0-9a-f]{4,}",  # CI: expect actual commit hash
    r"unknown \\(local build\\)"  # Local: expect placeholder
)

is_running_under_pytest() -> bool

from apathetic_utils import is_running_under_pytest

if is_running_under_pytest():
    # Use test-specific configuration
    pass

detect_runtime_mode(package_name: str) -> str

from apathetic_utils import detect_runtime_mode

mode = detect_runtime_mode("my_package")
print(f"Running in {mode} mode")

capture_output() -> ContextManager[CapturedOutput]

from apathetic_utils import capture_output
import sys

with capture_output() as cap:
    print("Hello, world!")
    print("Error message", file=sys.stderr)

print(f"stdout: {cap.stdout.getvalue()}")
print(f"stderr: {cap.stderr.getvalue()}")
print(f"merged: {cap.merged.getvalue()}")

# Or convert to dict
output = cap.as_dict()

get_sys_version_info() -> tuple[int, int, int] | tuple[int, int, int, str, int]

from apathetic_utils import get_sys_version_info

version = get_sys_version_info()
print(f"Python {version[0]}.{version[1]}.{version[2]}")

ensure_stitched_script_up_to_date(
    *,
    root: Path,
    script_name: str | None = None,
    package_name: str,
    command_path: str | None = None,
    log_level: str | None = None
) -> Path

from apathetic_utils import ensure_stitched_script_up_to_date
from pathlib import Path

# Using package_name as script_name (default)
script_path = ensure_stitched_script_up_to_date(
    root=Path("."),
    package_name="my_package"
)

# Using a custom script name
script_path = ensure_stitched_script_up_to_date(
    root=Path("."),
    script_name="my_script",
    package_name="my_package"
)

# Using a local bundler script
script_path = ensure_stitched_script_up_to_date(
    root=Path("."),
    script_name="my_script",
    package_name="my_package",
    command_path="bin/serger.py"
)

# Using a custom log level
script_path = ensure_stitched_script_up_to_date(
    root=Path("."),
    package_name="my_package",
    log_level="debug"
)

ensure_zipapp_up_to_date(
    *,
    root: Path,
    script_name: str | None = None,
    package_name: str,
    command_path: str | None = None,
    log_level: str | None = None
) -> Path

from apathetic_utils import ensure_zipapp_up_to_date
from pathlib import Path

# Using package_name as script_name (default)
zipapp_path = ensure_zipapp_up_to_date(
    root=Path("."),
    package_name="my_package"
)

# Using a custom script name
zipapp_path = ensure_zipapp_up_to_date(
    root=Path("."),
    script_name="my_script",
    package_name="my_package"
)

# Using a custom log level
zipapp_path = ensure_zipapp_up_to_date(
    root=Path("."),
    package_name="my_package",
    log_level="debug"
)

# Using a local bundler script
zipapp_path = ensure_zipapp_up_to_date(
    root=Path("."),
    package_name="my_package",
    command_path="bin/zipapp_builder.py"
)

runtime_swap(
    *,
    root: Path,
    package_name: str,
    script_name: str | None = None,
    stitch_command: str | None = None,
    zipapp_command: str | None = None,
    mode: str | None = None,
    log_level: str | None = None
) -> bool

from apathetic_utils import runtime_swap
from pathlib import Path

# In pytest conftest.py or similar
# Using package_name as script_name (default), Poetry-installed serger
runtime_swap(
    root=Path(__file__).parent.parent,
    package_name="my_package",
    mode="stitched"  # or None to read from RUNTIME_MODE env var
)

# Using a custom script name
runtime_swap(
    root=Path(__file__).parent.parent,
    package_name="my_package",
    script_name="my_script",
    mode="stitched"
)

# Using a local bundler script for stitched mode
runtime_swap(
    root=Path(__file__).parent.parent,
    package_name="my_package",
    script_name="my_script",
    stitch_command="bin/serger.py",
    mode="stitched"
)

# Using a local bundler script for zipapp mode
runtime_swap(
    root=Path(__file__).parent.parent,
    package_name="my_package",
    script_name="my_script",
    zipapp_command="bin/zipapp_builder.py",
    mode="zipapp"
)

# Using a custom log level
runtime_swap(
    root=Path(__file__).parent.parent,
    package_name="my_package",
    mode="stitched",
    log_level="debug"
)

run_with_output(
    args: list[str],
    *,
    cwd: Path | str | None = None,
    initial_env: dict[str, str] | None = None,
    env: dict[str, str] | None = None,
    forward_to: str | None = "normal",
    check: bool = False,
    **kwargs: Any
) -> SubprocessResult

from apathetic_utils import run_with_output
import sys

# Use current environment with additional vars
result = run_with_output(
    [sys.executable, "-m", "serger", "--config", "config.json"],
    cwd=tmp_path,
    env={"LOG_LEVEL": "test"},
)

# Forward output to bypass (visible in real-time, bypasses capsys)
result = run_with_output(
    [sys.executable, "-m", "serger", "--config", "config.json"],
    cwd=tmp_path,
    env={"LOG_LEVEL": "test"},
    forward_to="bypass",
)

# On test failure, output will be included
assert result.returncode == 0, f"Failed: {result.all_output}"

run_with_separated_output(
    args: list[str],
    *,
    cwd: Path | str | None = None,
    initial_env: dict[str, str] | None = None,
    env: dict[str, str] | None = None,
    check: bool = False,
    **kwargs: Any
) -> SubprocessResultWithBypass

from apathetic_utils import run_with_separated_output
import sys

result = run_with_separated_output(
    [sys.executable, "-m", "serger", "--config", "config.json"],
    cwd=tmp_path,
    env={"LOG_LEVEL": "test"},
)
# stdout contains normal output (captured)
# bypass_output contains output written to __stdout__
assert result.returncode == 0, f"Failed: {result.all_output}"

plural(obj: Any) -> str

from apathetic_utils import plural

count = 5
print(f"{count} file{plural(count)}")  # "5 files"

count = 1
print(f"{count} file{plural(count)}")  # "1 file"

items = [1, 2, 3]
print(f"{len(items)} item{plural(items)}")  # "3 items"

remove_path_in_error_message(inner_msg: str, path: Path) -> str

from apathetic_utils import remove_path_in_error_message
from pathlib import Path

error_msg = "Invalid JSONC syntax in /path/to/config.jsonc: Expecting value"
path = Path("/path/to/config.jsonc")

clean_msg = remove_path_in_error_message(error_msg, path)
# Returns: "Invalid JSONC syntax: Expecting value"

safe_isinstance(value: Any, expected_type: Any) -> bool

from apathetic_utils import safe_isinstance
from typing import TypedDict, Optional

class Config(TypedDict):
    name: str
    value: int

data = {"name": "test", "value": 42}

# Works with TypedDict
safe_isinstance(data, Config)  # True

# Works with generics
safe_isinstance([1, 2, 3], list[int])  # True
safe_isinstance({"a": 1, "b": 2}, dict[str, int])  # True

# Works with Optional
safe_isinstance(None, Optional[str])  # True
safe_isinstance("test", Optional[str])  # True

literal_to_set(literal_type: Any) -> set[Any]

from apathetic_utils import literal_to_set
from typing import Literal

Mode = Literal["dev", "prod", "test"]
valid_modes = literal_to_set(Mode)
# Returns: {"dev", "prod", "test"}

if "dev" in valid_modes:
    print("Valid mode")

cast_hint(typ: type[T], value: Any) -> T

from apathetic_utils import cast_hint

# Type narrowing for type checkers
value: Any = get_data()
typed_value = cast_hint(dict[str, int], value)
# typed_value is now inferred as dict[str, int]

schema_from_typeddict(td: type[Any]) -> dict[str, Any]

from apathetic_utils import schema_from_typeddict
from typing import TypedDict

class Config(TypedDict):
    name: str
    value: int

schema = schema_from_typeddict(Config)
# Returns: {"name": str, "value": int}

create_version_info(major: int, minor: int, micro: int = 0) -> Any

from apathetic_utils import create_version_info

version = create_version_info(3, 11)
assert version.major == 3
assert version.minor == 11
assert version >= (3, 10)

detect_module_runtime_mode(
    mod: ModuleType,
    *,
    stitch_hints: set[str] | None = None
) -> str

from apathetic_utils import detect_module_runtime_mode
import apathetic_utils

# Detect module runtime mode
mode = detect_module_runtime_mode(apathetic_utils)
print(f"apathetic_utils is running in {mode} mode")

# With custom stitch hints
mode = detect_module_runtime_mode(
    apathetic_utils,
    stitch_hints={"/dist/", "bundled", "embedded"}
)

create_mock_superclass_test(
    mixin_class: type,
    parent_class: type,
    method_name: str,
    camel_case_method_name: str,
    args: tuple[Any, ...],
    kwargs: dict[str, Any],
    monkeypatch: pytest.MonkeyPatch
) -> None

from apathetic_utils import create_mock_superclass_test
import logging
import pytest

def test_mixin_calls_parent(monkeypatch):
    create_mock_superclass_test(
        MyMixin,
        logging.Logger,
        "add_filter",
        "addFilter",
        (logging.Filter(),),
        {},
        monkeypatch
    )

patch_everywhere(
    mp: pytest.MonkeyPatch,
    mod_env: ModuleType | Any,
    func_name: str,
    replacement_func: Callable[..., object],
    *,
    package_prefix: str | Sequence[str],
    stitch_hints: set[str] | None = None,
    create_if_missing: bool = False,
    caller_func_name: str | None = None
) -> None

from apathetic_utils import patch_everywhere
import pytest
import my_module

def test_patch_function(monkeypatch):
    def mock_func():
        return "mocked"
    
    patch_everywhere(
        monkeypatch,
        my_module,
        "original_func",
        mock_func,
        package_prefix="my_module"
    )

CI_ENV_VARS: tuple[str, ...]

from apathetic_utils import CI_ENV_VARS

print(CI_ENV_VARS)  # ("CI", "GITHUB_ACTIONS", "GIT_TAG", "GITHUB_REF")

from apathetic_utils import apathetic_utils

# Use via namespace
config = apathetic_utils.load_jsonc(Path("config.jsonc"))
is_ci = apathetic_utils.is_ci()
mode = apathetic_utils.detect_runtime_mode("my_package")