pyhabitat 1.1.23__py3-none-any.whl

pyhabitat/reporting.py

@@ -0,0 +1,120 @@
+# src/pyhabitat/report.py 
+from __future__ import annotations  
+import sys
+import logging
+from pathlib import Path
+
+from pyhabitat import environment as env
+def report(path=None, debug=False):
+    """Print a comprehensive environment report.
+
+    Args:
+        path (Path | str | None): Path to inspect (defaults to sys.argv[0]).
+        debug (bool): Enable verbose debug output.
+    """
+    if debug:
+        logging.basicConfig(level=logging.DEBUG)
+        logging.getLogger('matplotlib').setLevel(logging.WARNING)  # Suppress matplotlib debug logs
+    print("================================")
+    print("======= PyHabitat Report =======")
+    print("================================")
+    print("\nCurrent Build Checks ")
+    print("# // Based on hasattr(sys,..) and getattr(sys,..)")
+    print("------------------------------")
+    print(f"in_repl(): {env.in_repl()}")
+    print(f"as_frozen(): {env.as_frozen()}")
+    print(f"as_pyinstaller(): {env.as_pyinstaller()}")
+    print("\nOperating System Checks")
+    print("# // Based on platform.system()")
+    print("------------------------------")
+    print(f"on_windows(): {env.on_windows()}")
+    print(f"on_macos(): {env.on_macos()}")
+    print(f"on_linux(): {env.on_linux()}")
+    print(f"on_wsl(): {env.on_wsl()}")
+    print(f"on_android(): {env.on_android()}")
+    print(f"on_termux(): {env.on_termux()}")
+    print(f"on_pydroid(): {env.on_pydroid()}")
+    print(f"on_ish_alpine(): {env.on_ish_alpine()}")
+    print(f"on_freebsd(): {env.on_freebsd()}")
+    print("\nCapability Checks")
+    print("-------------------------")
+    print(f"tkinter_is_available(): {env.tkinter_is_available()}")
+    print(f"matplotlib_is_available_for_gui_plotting(): {env.matplotlib_is_available_for_gui_plotting()}")
+    print(f"matplotlib_is_available_for_headless_image_export(): {env.matplotlib_is_available_for_headless_image_export()}")
+    print(f"web_browser_is_available(): {env.web_browser_is_available()}")
+    print(f"interactive_terminal_is_available(): {env.interactive_terminal_is_available()}")
+    print("\nInterpreter Checks")
+    print("# // Based on sys.executable()")
+    print("-----------------------------")
+    print(f"interp_path(): {env.interp_path()}")
+    if debug:
+        # Do these debug prints once to avoid redundant prints
+        # Supress redundant prints explicity using suppress_debug=True, 
+        # so that only unique information gets printed for each check, 
+        # even when more than one use the same functions which include debugging logs.
+        #print(f"env.check_executable_path(env.interp_path(), debug=True)")
+        env.check_executable_path(env.interp_path(), debug=debug)    
+        #print(f"read_magic_bites(env.interp_path(), debug=True)")
+        env.read_magic_bytes(env.interp_path(), debug=debug)
+    print(f"is_elf(env.interp_path()): {env.is_elf(env.interp_path(), debug=debug, suppress_debug=True)}")
+    print(f"is_windows_portable_executable(env.interp_path()): {env.is_windows_portable_executable(env.interp_path(), debug=debug, suppress_debug=True)}")
+    print(f"is_macos_executable(env.interp_path()): {env.is_macos_executable(env.interp_path(), debug=debug, suppress_debug=True)}")
+    print(f"is_pyz(env.interp_path()): {env.is_pyz(env.interp_path(), debug=debug, suppress_debug=True)}")
+    print(f"is_pipx(env.interp_path()): {env.is_pipx(env.interp_path(), debug=debug, suppress_debug=True)}")
+    print(f"is_python_script(env.interp_path()): {env.is_python_script(env.interp_path(), debug=debug, suppress_debug=True)}")
+    print("\nCurrent Environment Check")
+    print("# // Based on sys.argv[0]")
+    print("-----------------------------")
+    inspect_path = path if path is not None else (None if sys.argv[0] == '-c' else sys.argv[0])
+    logging.debug(f"Inspecting path: {inspect_path}")
+    # Early validation of path
+    if path is not None:
+        path_obj = Path(path)
+        if not path_obj.is_file():
+            print(f"Error: '{path}' is not a valid file or does not exist.")
+            if debug:
+                logging.error(f"Invalid path: '{path}' is not a file or does not exist.")
+            raise SystemExit(1)
+    script_path = None
+    if path or (sys.argv[0] and sys.argv[0] != '-c'):
+        script_path = Path(path or sys.argv[0]).resolve()
+    print(f"sys.argv[0] = {str(sys.argv[0])}")
+    if script_path is not None:
+        print(f"script_path = {script_path}")
+        if debug:
+            # Do these debug prints once to avoid redundant prints
+            # Supress redundant prints explicity using suppress_debug=True, 
+            # so that only unique information gets printed for each check, 
+            # even when more than one use the same functions which include debugging logs.
+            #print(f"check_executable_path(script_path, debug=True)")
+            env.check_executable_path(script_path, debug=debug)
+            #print(f"read_magic_bites(script_path, debug=True)")
+            env.read_magic_bytes(script_path, debug=debug)
+        print(f"is_elf(): {env.is_elf(script_path, debug=debug, suppress_debug=True)}")
+        print(f"is_windows_portable_executable(): {env.is_windows_portable_executable(script_path, debug=debug, suppress_debug=True)}")
+        print(f"is_macos_executable(): {env.is_macos_executable(script_path, debug=debug, suppress_debug=True)}")
+        print(f"is_pyz(): {env.is_pyz(script_path, debug=debug, suppress_debug=True)}")
+        print(f"is_pipx(): {env.is_pipx(script_path, debug=debug, suppress_debug=True)}")
+        print(f"is_python_script(): {env.is_python_script(script_path, debug=debug, suppress_debug=True)}")
+    else:
+        print("Skipping: ") 
+        print("    is_elf(), ")
+        print("    is_windows_portable_executable(), ")
+        print("    is_macos_executable(), ")
+        print("    is_pyz(), ")
+        print("    is_pipx(), ") 
+        print("    is_python_script(), ")
+        print("All False, script_path is None.")
+    print("")
+    print("=================================")
+    print("=== PyHabitat Report Complete ===")
+    print("=================================")
+    print("")
+    interactive = env.in_repl() or sys.flags.interactive
+    if not interactive:
+        # Keep window open.
+        try:
+            input("Press Return to Continue...")
+        except Exception as e:
+            logging.debug("input() failed")
+               

pyhabitat/system_info.py

@@ -0,0 +1,131 @@
+# src/pyhabitat/system_info.py
+from __future__ import annotations
+import platform
+import sys
+from pathlib import Path
+import os
+
+try:
+    import distro  # external package, best for Linux detection, but pyhabitat doesnt use external packages
+except ImportError:
+    distro = None
+
+class SystemInfo:
+    """Detects the current OS, distro, and version information."""
+
+    def __init__(self):
+        self.system = platform.system()  # "Windows", "Linux", "Darwin"
+        self.release = platform.release()
+        self.version = platform.version()
+        self.architecture = platform.machine()
+
+    def detect_linux_distro(self) -> dict:
+        """Return Linux distribution info (if available)."""
+        if self.system != "Linux":
+            return {}
+
+        if distro:
+            return {
+                "id": distro.id(),
+                "name": distro.name(),
+                "version": distro.version(),
+                "like": distro.like(),
+            }
+        else:
+            # fallback to /etc/os-release parsing
+            os_release = Path("/etc/os-release")
+            if os_release.exists():
+                info = {}
+                for line in os_release.read_text().splitlines():
+                    if "=" in line:
+                        k, v = line.split("=", 1)
+                        info[k.strip()] = v.strip().strip('"')
+                return {
+                    "id": info.get("ID"),
+                    "name": info.get("NAME"),
+                    "version": info.get("VERSION_ID"),
+                    "like": info.get("ID_LIKE"),
+                }
+            return {"id": "unknown", "name": "unknown", "version": "unknown"}
+
+    def detect_android_termux(self) -> bool:
+        if "ANDROID_ROOT" in os.environ or "TERMUX_VERSION" in os.environ:
+            return True
+        if "android" in self.release.lower():
+            return True
+        return False
+    
+    def get_windows_tag(self) -> str:
+        """Differentiate Windows 10 vs 11 based on build number."""
+        release, version, csd, ptype = platform.win32_ver()
+        try:
+            build_number = int(version.split(".")[-1])
+        except Exception:
+            build_number = 0
+
+        if build_number >= 22000:
+            return "windows11"
+        return "windows10"
+    
+    def get_os_tag(self) -> str:
+        """Return a compact string for use in filenames (e.g. ubuntu22.04)."""
+        if self.system == "Windows":
+            return self.get_windows_tag()
+
+        if self.system == "Darwin":
+            mac_ver = platform.mac_ver()[0].split(".")[0] or "macos"
+            return f"macos{mac_ver}"
+
+        if self.system == "Linux":
+            if self.detect_android_termux():
+                return "android"
+
+            info = self.detect_linux_distro()
+            distro_id = info.get("id") or "linux"
+            distro_ver = (info.get("version") or "").replace(".", "")
+            if distro_ver:
+                return f"{distro_id}{info['version']}"
+            return distro_id
+
+        return self.system.lower()
+    
+    def get_arch(self) -> str:
+        arch = self.architecture.lower()
+        if arch in ("amd64", "x86_64"):
+            return "x86_64"
+        return self.architecture
+    
+    def to_dict(self) -> dict:
+        """Return a full snapshot of system information."""
+        info = {
+            "system": self.system,
+            "release": self.release,
+            "version": self.version,
+            "arch": self.architecture,
+            "os_tag": self.get_os_tag(),
+        }
+        if self.system == "Linux" and self.detect_android_termux():
+            info["id"] = "android"
+            info["name"] = "Android (Termux)"
+        elif self.system == "Linux":
+            info.update(self.detect_linux_distro())
+        elif self.system == "Windows":
+            info["win_version"] = platform.win32_ver()
+        elif self.system == "Darwin":
+            info["mac_ver"] = platform.mac_ver()[0]
+        return info
+
+    def pretty_print(self):
+        """Nicely formatted printout of system info."""
+        info = self.to_dict()
+        print("--- System Information ---")
+        for k, v in info.items():
+            print(f"{k:10}: {v}")
+
+
+if __name__ == "__main__":
+    sysinfo = SystemInfo()
+    sysinfo.pretty_print()
+    sysinfo.get_os_tag()
+    sysinfo.get_arch()
+    

pyhabitat/version_info.py

@@ -0,0 +1,209 @@
+# src/pyhabitat/version_info
+from __future__ import annotations # Delays annotation evaluation, allowing modern 3.10+ type syntax and forward references in older Python versions 3.8 and 3.9
+import sys
+from pathlib import Path  
+import re
+
+try:
+    # Python 3.8+
+    from importlib import metadata
+    PackageNotFoundError = metadata.PackageNotFoundError
+except (ImportError, AttributeError):
+    try:
+        # Python 3.7 Backport
+        import importlib_metadata as metadata
+        PackageNotFoundError = metadata.PackageNotFoundError
+    except ImportError:
+        metadata = None
+        # Define a dummy exception so the code doesn't crash on 3.7 
+        # if the backport is missing
+        class PackageNotFoundError(Exception): pass
+
+from .system_info import SystemInfo
+
+# -- Versioning --
+PIP_PACKAGE_NAME = "pyhabitat"
+# Auto-detected at build time (fallback)
+FALLBACK_VERSION = "dev"
+
+
+def _running_inside_pyinstaller() -> bool:
+    return hasattr(sys, "_MEIPASS")
+
+def _read_embedded_version() -> str | None:
+    # Check PyInstaller runtime
+    if _running_inside_pyinstaller():
+        base = Path(sys._MEIPASS)  # temp folder where PyInstaller unpacks files
+    else:
+        base = Path(__file__).parent
+
+    try:
+        return (base / "VERSION").read_text().strip()
+    except Exception:
+        return None
+
+
+def find_pyproject(start: Path) -> Path | None:
+    # Look back up to 3 levels: pyhabitat/, src/, project_root/
+    # This covers the src-layout structure you showed.
+    # Ensure we start at the directory of the file, resolved to absolute path
+    current = start.resolve().parent if start.is_file() else start.resolve()
+    
+    # Climb up to 3 levels (package -> src -> project_root)
+    for _ in range(4):
+        candidate = current / "pyproject.toml"
+        if candidate.exists():
+            if _ensure_relevant_pyproject_file(candidate):
+                return candidate
+        # Move up one level for the next iteration
+        if current.parent == current: break # Hit root
+        current = current.parent
+        
+    return None
+
+def _ensure_relevant_pyproject_file(candidate):
+    content = candidate.read_text(encoding="utf-8")
+    # Ensure this TOML defines 'name = "pyhabitat"' 
+    # (handles both [project] and [tool.poetry] name definitions)
+    name_match = re.search(r'^name\s*=\s*["\']pyhabitat["\']', content, re.MULTILINE)
+    poetry_name_match = re.search(r'\[tool\.poetry\].*?name\s*=\s*["\']pyhabitat["\']', content, re.DOTALL)
+    
+    if name_match or poetry_name_match:
+        return True
+    else:
+        return False
+
+def get_package_name() -> str:
+    # 1. Check pyproject.toml FIRST (Crucial for Build/Dev environments)
+    try:
+        pyproject = find_pyproject(Path(__file__))
+        if pyproject:
+            content = pyproject.read_text(encoding="utf-8")
+            match = re.search(r'^\s*name\s*=\s*["\']([^"\']+)["\']', content, re.MULTILINE)
+            if match:
+                return match.group(1)
+    except Exception:
+        pass
+
+    # 2. Check installed metadata (If running from a pip/pipx install)
+    if metadata:
+        try:
+            return metadata(PIP_PACKAGE_NAME)["Name"]
+        except Exception:
+            pass
+
+    # 3. Final Hardcoded Fallback
+    return PIP_PACKAGE_NAME
+
+
+def get_version_for_build() -> str:
+    return get_version_from_pyproject()
+
+def get_version_from_pyproject() -> str:
+    """
+    Read the version from pyproject.toml without external dependencies.
+    Handles both Poetry and PEP-621 formats:
+        version = "0.1.0"
+        [project]
+        version = "0.1.0"
+    """
+    pyproject = find_pyproject(Path(__file__))
+    
+
+    if not pyproject or not pyproject.exists():
+        return "Unknown (pyproject.toml missing)"
+
+    text = pyproject.read_text(encoding="utf-8")
+    #print(text)
+    # 1. Match PEP 621 style:
+    #    version = "0.1.0" inside a [project] table
+    project_section = re.search(
+        r"\[project\](.*?)(?:\n\[|$)",
+        text,
+        re.DOTALL | re.IGNORECASE,
+    )
+    if project_section:
+        match = re.search(
+            r'version\s*=\s*["\']([^"\']+)["\']',
+            project_section.group(1),
+        )
+        if match:
+            return match.group(1)
+
+    # 2. Match Poetry style:
+    #    [tool.poetry]
+    #    version = "0.1.0"
+    poetry_section = re.search(
+        r"\[tool\.poetry\](.*?)(?:\n\[|$)",
+        text,
+        re.DOTALL | re.IGNORECASE,
+    )
+    if poetry_section:
+        match = re.search(
+            r'version\s*=\s*["\']([^"\']+)["\']',
+            poetry_section.group(1),
+        )
+        if match:
+            return match.group(1)
+
+    # fallback
+    return "Unknown (version not found)"
+
+
+def get_package_version() -> str:
+    """
+    Correct priority:
+    
+    1. embedded VERSION file (inside .pyz)
+    2. pyproject.toml (local source)
+    3. installed package metadata (pip)
+    4. fallback
+    """
+
+     # 1. Running inside a binary / .pyz
+    v = _read_embedded_version()
+    if v:
+        return v
+
+    # 3. Check installed metadata (Only if metadata lib is available)
+    if metadata:
+        try:
+            return metadata.version(PIP_PACKAGE_NAME)
+        except (metadata.PackageNotFoundError, AttributeError):
+            pass
+
+    # 3. Local source tree → pyproject.toml
+    v = get_version_from_pyproject()
+    if v and not v.startswith("Unknown"):
+        return v
+    
+    
+
+
+    # 4. Default
+    return FALLBACK_VERSION
+
+
+def get_python_version():
+    py_major = sys.version_info.major
+    py_minor = sys.version_info.minor
+    py_version = f"py{py_major}{py_minor}"
+    return py_version
+
+def form_dynamic_binary_name(package_name: str, package_version: str, py_version: str, os_tag: str, arch: str) -> str:    
+    # Use hyphens for the CLI/EXE/ELF name
+    return f"{package_name}-{package_version}-{py_version}-{os_tag}-{arch}"
+
+__version__ = get_package_version()
+
+if __name__ == "__main__":
+    package_name = get_package_name()
+    package_version = get_package_version()
+    py_version = get_python_version()
+    
+    sysinfo = SystemInfo()
+    os_tag = sysinfo.get_os_tag()
+    architecture = sysinfo.get_arch()
+
+    bin_name = form_dynamic_binary_name(package_name, package_version, py_version, os_tag, architecture)
+    print(f"bin_name = {bin_name}")

pyhabitat-1.1.23.dist-info/METADATA

@@ -0,0 +1,226 @@
+Metadata-Version: 2.4
+Name: pyhabitat
+Version: 1.1.23
+Summary: A lightweight library for detecting system environment, GUI, and build properties.
+Author-email: George Clayton Bennett <george.bennett@memphistn.gov>
+Maintainer-email: George Clayton Bennett <george.bennett@memphistn.gov>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/city-of-memphis-wastewater/pyhabitat
+Project-URL: Repository, https://github.com/city-of-memphis-wastewater/pyhabitat
+Keywords: environment,platform-detection,os-detection,container,docker,wsl,termux,unix,windows,macos,ci,runtime-detection
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: System :: Operating System
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: importlib-metadata; python_version < "3.8"
+Dynamic: license-file
+
+# pyhabitat 🧭
+
+## An Introspection Library for Python Environments and Builds
+
+**`pyhabitat`** is a **lightweight library for Python build and environment introspection**. It accurately and securely determines the execution context of a running script by providing definitive checks for:
+
+* **OS and Environments:** Operating Systems and common container/emulation environments (e.g., Termux, iSH).
+* **Build States:** Application build systems (e.g., PyInstaller, pipx).
+* **GUI Backends:** Availability of graphical toolkits (e.g., Matplotlib, Tkinter).
+
+Stop writing verbose `sys.platform` and environment variable checks. Use **`pyhabitat`** to implement clean, **architectural logic** based on the execution habitat.
+
+---
+
+Read the code on [github](https://github.com/City-of-Memphis-Wastewater/pyhabitat/blob/main/pyhabitat/environment.py). 🌐
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/City-of-Memphis-Wastewater/pyhabitat/main/assets/pyhabitat-ico-alpha.png" width="256px">
+</p>
+<!--p align="center">
+  <img src="https://raw.githubusercontent.com/City-of-Memphis-Wastewater/pyhabitat/main/assets/pyhabitat-ico_256x256.ico" width="200" alt="ICO Version" />
+</p-->
+
+---
+
+## 📦 Installation
+
+```bash
+pip install pyhabitat
+```
+
+---
+
+<details>
+<summary> 🧠 Motivation </summary>
+
+This library is especially useful for **leveraging Python in mobile environments** (`Termux` on Android and `iSH` on iOS), which often have particular limitations and require special handling. For example, projects use pyhabitat in their logic to trigger **localhost plotting** when a GUI is not available. You can set different behaviors for pyhabitat.on_wsl(), pyhabitat.on_termux(), pyhabitat.on_windows(), and pyhabitat.on_linux(). 
+
+Our team is fundamentally driven by enabling mobile computing for true utility applications.
+We liked it when our CLI's and our servers run on every device in the drawer.
+
+This project has a `pipx` installable **CLI**
+
+Ultimately, [City-of-Memphis-Wastewater](https://github.com/City-of-Memphis-Wastewater) aims to produce **reference-quality code** for the documented proper approach. We recognize that many people (and bots) are searching for ideal solutions, and our functions are built upon extensive research and testing to go **beyond simple `platform.system()` checks**.
+
+</details>
+
+---
+
+<details>
+<summary> 🚀 Features </summary>
+
+  * **Definitive Environment Checks:** Rigorous checks catered to Termux and iSH (iOS Alpine). Accurate, typical modern detection for Windows, macOS (Apple), Linux, FreeBSD, Android.
+  * **GUI Availability:** Rigorous, cached checks to determine if the environment supports a graphical popup window (Tkinter/Matplotlib TkAgg) or just headless image export (Matplotlib Agg).
+  * **Build/Packaging Detection:** Reliable detection of standalone executables (PyInstaller), Python zipapps (.pyz), Python source scripts (.py), and correct identification/exclusion of pipx-managed virtual environments.
+  * **Executable Type Inspection:** Uses file magic numbers (ELF, MZ, Mach-O) to confirm if the running script is a monolithic, frozen binary (non-pipx) or zipapp (.pyz).
+
+</details>
+
+---
+
+<details>
+<summary> 📚 Function Reference </summary>
+
+### OS and Environment Checking
+
+Key question: "What is this running on?"
+
+| Function | Description |
+| :--- | :--- |
+| `on_windows()` | Returns `True` on Windows. |
+| `on_macos()` | Returns `True` on macOS (Darwin). |
+| `on_linux()` | Returns `True` on Linux in general. |
+| `on_wsl()` | Returns `True` if running inside Windows Subsystem for Linux (WSL or WSL2). |
+| `on_termux()` | Returns `True` if running in the Termux Android environment. |
+| `on_freebsd()` | Returns `True` on FreeBSD. |
+| `on_ish_alpine()` | Returns `True` if running in the iSH Alpine Linux iOS emulator. |
+| `on_android()` | Returns `True` on any Android-based Linux environment. |
+| `on_pydroid()` | Returns `True` Return True if running under the Pydroid 3 Android app (other versions untested). |
+| `in_repl()` | Returns `True` is the user is currently in a Python REPL; hasattr(sys,'ps1'). |
+
+### Packaging and Build Checking
+
+Key question: "What is the character of my executable or my build state?"
+
+These functions accept an optional path argument (Path or str), defaulting to sys.argv[0] (e.g., pyhabitat/__main__.py for python -m pyhabitat, empty in REPL). Path.resolve() is used for stability.
+
+| Function | Description |
+| :--- | :--- |
+| `as_frozen()` | Returns `True` if the script is running as a standalone executable (any bundler). |
+| `as_pyinstaller()` | Returns `True` if the script is frozen and generated by PyInstaller (has `_MEIPASS`). |
+| `is_python_script(path=None)` | Returns `True` if the script or specified path is a Python source file (.py). |
+| `is_pipx(path=None)` | Returns `True` if the script or specified path is from a pipx-managed virtual environment. |
+| `is_elf(path=None)` | Returns `True` if the script or specified path is an ELF binary (Linux standalone executable, non-pipx). |
+| `is_pyz(path=None)` | Returns `True` if the script or specified path is a Python zipapp (.pyz, non-pipx). |
+| `is_windows_portable_executable(path=None)` | Returns `True` if the script or specified path is a Windows PE binary (MZ header, non-pipx). |
+| `is_msix()` | Returns `True` if the currently running software or the target path is an MSIX package, like distributed from the Microsoft Store. |
+| `is_macos_executable(path=None)` | Returns `True` if the script or specified path is a macOS Mach-O binary (non-pipx). |
+
+### Capability Checking
+
+Key Question: "What could I do next?"
+
+| Function | Description |
+| :--- | :--- |
+| `tkinter_is_available()` | Checks if Tkinter is imported and can successfully create a window. |
+| `matplotlib_is_available_for_gui_plotting(termux_has_gui=False)` | Checks for Matplotlib and its TkAgg backend, required for interactive plotting. Set `termux_has_gui=True` for Termux with GUI support; defaults to `False`. |
+| `matplotlib_is_available_for_headless_image_export()` | Checks for Matplotlib and its Agg backend, required for saving images without a GUI. |
+| `interactive_terminal_is_available()` | Checks if standard input and output streams are connected to a TTY (allows safe use of interactive prompts). |
+| `web_browser_is_available()` | Check if a web browser can be launched in the current environment (allows safe use of web-based prompts and localhost plotting). 	|
+
+### Utility
+
+| Function | Description |
+| :--- | :--- |
+| `edit_textfile(path)` | Opens a text file for editing using the default editor (Windows, Linux, macOS) or nano in Termux/iSH. Can be called from REPL mode. Path argument (str or Path) uses Path.resolve() for stability. |
+| `show_system_explorer(path)` | Launches the appropriate view of the folder based on system. Defaults to Path.cwd(). |
+| `interp_path()` | Returns the path to the Python interpreter binary (sys.executable). Returns empty string if unavailable. |
+| `report()` | Prints a comprehensive environment report with sections: Interpreter Checks (sys.executable), Current Environment Check (sys.argv[0]), Current Build Checks (sys attributes), Operating System Checks (platform.system()), and Capability Checks. Run via `python -m pyhabitat` or `import pyhabitat; pyhabitat.main()` in the REPL. |
+
+</details>
+
+---
+
+<details>
+<summary> 💻 Usage Examples </summary>
+
+The module exposes all detection functions directly for easy access.
+
+### 0\. Example of PyHabitat in Action
+
+The `pyhabitat` library is used extensively in [PDF Link Check](https://github.com/City-of-Memphis-Wastewater/pipeline/blob/main/src/pipeline/security_and_config.py) and [plotting](https://github.com/City-of-Memphis-Wastewater/pdflinkcheck/blob/main/pyproject.toml).
+
+### 1\. Running the Environment Report
+
+Run a comprehensive environment report from the command line or REPL to inspect the interpreter (sys.executable), running script (sys.argv[0]), build state, operating system, and capabilities.
+
+```bash
+# In the terminal
+python -m pyhabitat
+```
+
+```python
+# In the Python REPL
+import pyhabitat as ph
+ph.report()
+```
+
+### Text Editing
+
+Use this function to open a text file for editing. 
+Ideal use case: Edit a configuration file, if prompted by a CLI command like 'config --textedit'.
+
+```python
+from pathlib import Path
+import pyhabitat as ph
+
+ph.edit_textfile(path=Path('./config.json'))
+```
+</details>
+
+---
+
+<details> <summary>🏗️ Build Instructions</summary>
+
+### Build Options
+
+You can build PyHabitat in two ways:
+
+| Output  | Command                      | Notes                                                                 |
+|---------|------------------------------|-------------------------|
+| PYZ     | `python build_pyz.py`        | Cross-platform zipapp   |
+| EXE/ELF | `python build_executable.py` | PyIndtaller executable  |
+
+
+✅ Notes:
+
+.pyz is cross-platform but requires Python on the host system.
+
+</details>
+
+---
+
+
+🤝 Contributing
+
+
+Contributions are welcome\! If there is an environment or build system that is not correctly detected, or that you would like to have added, please open an issue or submit a pull request with the relevant detection logic.
+
+## 📄 License
+
+This project is licensed under the MIT License. See the LICENSE file for details.
+
+---
+