File: Broken/__init__.py¶

class Environment:
    """Utilities for managing environment variables"""

    def __new__(cls) -> None:
        raise TypeError(f"{cls.__name__} class cannot be instantiated")

    @staticmethod
    def set(key: str, value: str | None, /) -> None:
        if (value is not None):
            os.environ[key] = str(value)

    @staticmethod
    def append(key: str, value: str | None, /, pad: str=" ") -> None:
        if (key not in os.environ):
            Environment.set(key, value)
        elif (value is not None):
            os.environ[key] += pad + str(value)

    @staticmethod
    def setdefault(key: str, value: str | None, /) -> None:
        if (value is not None):
            os.environ.setdefault(key, str(value))

    @staticmethod
    def update(**values: str | None) -> None:
        for key, value in values.items():
            Environment.set(key, value)

    @staticmethod
    def get(key: str, default: str=None, /) -> str:
        return os.getenv(key, default)

    @staticmethod
    def exists(key: str, /) -> bool:
        return (key in os.environ)

    @staticmethod
    def int(key: str, default: int=0, /) -> int:
        return int(os.getenv(key, default))

    @staticmethod
    def float(key: str, default: float=1.0, /) -> float:
        return float(os.getenv(key, default))

    @staticmethod
    def bool(key: str, default: bool=False, /) -> bool:
        value = str(os.getenv(key, default)).lower()

        if value in ("1", "true", "yes", "on"):
            return True
        elif value in ("0", "false", "no", "off"):
            return False

        raise ValueError(f"Invalid boolean value for environment variable '{key}': {value}")

    @staticmethod
    def flag(key: str, default: bool=False, /) -> bool:
        return Environment.bool(key, default)

    @staticmethod
    def unset(key: str, /) -> None:
        os.unsetenv(key)

class Runtime:
    """Information about the current runtime environment"""

    Version: str = __version__
    """The version of the Broken library, and subsequently all projects"""

    # # Bitness

    Bitness: int = (struct.calcsize("P") * 8)
    """The word size of the Python interpreter (32, 64 bits)"""

    Python32: bool = (Bitness == 32)
    """True if running on a 32-bit Python interpreter"""

    Python64: bool = (Bitness == 64)
    """True if running on a 64-bit Python interpreter"""

    # # Runtime environments

    PyInstaller: bool = bool(getattr(sys, "frozen", False))
    """True if running from a PyInstaller binary build (https://github.com/pyinstaller/pyinstaller)"""

    Nuitka: bool = ("__compiled__" in globals())
    """True if running from a Nuitka binary build (https://github.com/Nuitka/Nuitka)"""

    PyApp: bool = Environment.exists("PYAPP")
    """True if running as a PyApp release (https://github.com/ofek/pyapp)"""

    PyPI: bool = any((part in __file__.lower() for part in ("site-packages", "dist-packages")))
    """True if running as a installed package from PyPI (https://brokensrc.dev/get/pypi/)"""

    Binary: bool = (PyInstaller or Nuitka or PyApp)
    """True if running from any executable build (PyInstaller, Nuitka, PyApp)"""

    Release: bool = (Binary or PyPI)
    """True if running from any static final release build (PyInstaller, Nuitka, PyApp, PyPI)"""

    Source: bool = (not Release)
    """True if running directly from the source code (https://brokensrc.dev/get/source/)"""

    Method: str = (Source and "Source") or (Binary and "Binary") or (PyPI and "PyPI")
    """The runtime environment of the current project release (Source, Release, PyPI)"""

    # # Special and Containers

    Docker: bool = Path("/.dockerenv").exists()
    """True if running from a Docker container"""

    GitHub: bool = Environment.exists("GITHUB_ACTIONS")
    """True if running in a GitHub Actions CI environment (https://github.com/features/actions)"""

    WSL: bool = Path("/usr/lib/wsl/lib").exists()
    """True if running in Windows Subsystem for Linux (https://learn.microsoft.com/en-us/windows/wsl/about)"""

    Interactive: bool = sys.stdout.isatty()
    """True if running in an interactive terminal session (user can input)"""

class Tools:
    """Shortcuts to common tools and utilities"""

    python: Path = Path(sys.executable)
    """The current Python interpreter executable"""

    uv: list[str, Path] = [python, "-m", "uv"]
    """Entry point for the uv package manager (https://github.com/astral-sh/uv)"""

    pip: list[str, Path] = [python, "-m", "uv", "pip"]
    """Entry point for pip"""