runtime

runtime

SERVER_PORT = 8050 module-attribute

HTTP port used by the local Dash server.

AppMeta dataclass

Define application metadata.

Source code in runtime.py

@dataclass(frozen=True)
class AppMeta:
    """Define application metadata."""

    name: str
    version: str
    author: str

RuntimeContext dataclass

Define runtime context for the current OS and execution mode.

Attributes:

Name	Type	Description
meta	AppMeta	Application metadata.
app_data_dir	Path	Per-user application data directory.
run_dir	Path	Directory containing the executable or source entry point.
is_frozen	bool	True when running as a bundled executable (PyInstaller).
net_backend	str	Network connection backend name.
net_backend_version	str	Network backend version.

Source code in runtime.py

@dataclass(frozen=True)
class RuntimeContext:
    """Define runtime context for the current OS and execution mode.

    Attributes:
        meta: Application metadata.
        app_data_dir: Per-user application data directory.
        run_dir: Directory containing the executable or source entry point.
        is_frozen: True when running as a bundled executable (PyInstaller).
        net_backend: Network connection backend name.
        net_backend_version: Network backend version.
    """

    meta: AppMeta
    app_data_dir: Path
    run_dir: Path
    is_frozen: bool
    net_backend: str
    net_backend_version: str
    server_host: str
    server_port: int
    is_docker: bool

    @property
    def geo_data_dir(self) -> Path:
        """Return the directory containing GeoIP databases."""
        return self.app_data_dir

geo_data_dir property

Return the directory containing GeoIP databases.

ensure_app_data_dir(app_dir)

Create the application data directory and README.txt file when missing.

Source code in app_dirs.py

def ensure_app_data_dir(app_dir: Path) -> None:
    """Create the application data directory and README.txt file when missing."""
    app_dir = app_dir.expanduser()
    app_dir.mkdir(parents=True, exist_ok=True)

    readme = app_dir / "README.txt"
    if not readme.exists():
        readme.write_text(README_TEXT, encoding="utf-8")

ensure_native_app_data_dir(app_name=APP_NAME)

Return native app data directory and ensure it exists.

Source code in app_dirs.py

def ensure_native_app_data_dir(app_name: str = APP_NAME) -> Path:
    """Return native app data directory and ensure it exists."""
    app_dir = get_native_app_data_dir(app_name)
    ensure_app_data_dir(app_dir)
    return app_dir

_get_app_data_dir(meta)

Return application data directory for the current runtime.

Source code in runtime.py

def _get_app_data_dir(meta: AppMeta) -> Path:
    """Return application data directory for the current runtime."""
    data_dir = os.environ.get("TAPMAP_DATA_DIR")
    if data_dir:
        app_dir = Path(data_dir)
        ensure_app_data_dir(app_dir)
        return app_dir

    return ensure_native_app_data_dir(meta.name)

_get_server_host()

Return server bind host for the current runtime.

Source code in runtime.py

def _get_server_host() -> str:
    """Return server bind host for the current runtime."""
    return os.environ.get("TAPMAP_HOST", "127.0.0.1")

_get_server_port()

Return server port for the current runtime.

Source code in runtime.py

def _get_server_port() -> int:
    """Return server port for the current runtime."""
    return int(os.environ.get("TAPMAP_PORT", str(SERVER_PORT)))

_detect_docker()

Return True when running in Docker.

Source code in runtime.py

def _detect_docker() -> bool:
    """Return True when running in Docker."""
    return os.environ.get("TAPMAP_IN_DOCKER") == "1"

build_runtime(meta)

Build the runtime context for the current OS and execution mode.

Source code in runtime.py

def build_runtime(meta: AppMeta) -> RuntimeContext:
    """Build the runtime context for the current OS and execution mode."""
    is_frozen = bool(getattr(sys, "frozen", False))
    run_dir = (
        Path(sys.executable).resolve().parent if is_frozen else Path(__file__).resolve().parent
    )

    app_data_dir = _get_app_data_dir(meta)
    net_backend, net_backend_version = _detect_network_backend()
    server_host = _get_server_host()
    server_port = _get_server_port()
    is_docker = _detect_docker()

    return RuntimeContext(
        meta=meta,
        app_data_dir=app_data_dir,
        run_dir=run_dir,
        is_frozen=is_frozen,
        net_backend=net_backend,
        net_backend_version=net_backend_version,
        server_host=server_host,
        server_port=server_port,
        is_docker=is_docker,
    )

_detect_network_backend()

Return network backend name and version.

Source code in runtime.py

def _detect_network_backend() -> tuple[str, str]:
    """Return network backend name and version."""
    system = platform.system()

    if system in {"Windows", "Linux"}:
        import psutil

        return "psutil", getattr(psutil, "__version__", "-")

    return "unknown", "unknown"