pyhabitat 1.0.16__py3-none-any.whl → 1.0.18__py3-none-any.whl

pyhabitat/__init__.py

@@ -4,23 +4,27 @@ from .environment import (
     matplotlib_is_available_for_gui_plotting,
     matplotlib_is_available_for_headless_image_export,
     tkinter_is_available,
-    is_termux,
-    is_freebsd,
-    is_linux,
-    is_android,
-    is_windows,
-    is_apple,
-    is_ish_alpine,
-    is_pyinstaller,
-    is_frozen,
+    in_repl,
+    on_termux,
+    on_freebsd,
+    on_linux,
+    on_android,
+    on_windows,
+    on_apple,
+    on_ish_alpine,
+    as_pyinstaller,
+    as_frozen,
     is_elf,
     is_pyz,
     is_windows_portable_executable,
     is_macos_executable,
     is_pipx,
+    is_python_script,
     interactive_terminal_is_available,
     web_browser_is_available,
     edit_textfile,
+    interp_path,
+    main,
 )
 
 # Optional: Set __all__ for explicit documentation and cleaner imports
@@ -28,21 +32,25 @@ __all__ = [
     'matplotlib_is_available_for_gui_plotting',
     'matplotlib_is_available_for_headless_image_export',
     'tkinter_is_available',
-    'is_termux',
-    'is_freebsd',
-    'is_linux',
-    'is_android',
-    'is_windows',
-    'is_apple',
-    'is_ish_alpine',
-    'is_pyinstaller',
-    'is_frozen',
+    'in_repl',
+    'on_termux',
+    'on_freebsd',
+    'on_linux',
+    'on_android',
+    'on_windows',
+    'on_apple',
+    'on_ish_alpine',
+    'as_pyinstaller',
+    'as_frozen',
     'is_elf',
     'is_pyz',
     'is_windows_portable_executable',
     'is_macos_executable',
     'is_pipx',
+    'is_python_script',
     'interactive_terminal_is_available',
     'web_browser_is_available',
     'edit_textfile',
+    'interp_path',
+    'main',
 ]

pyhabitat/__main__.py

@@ -0,0 +1,4 @@
+from .cli import run_cli
+
+if __name__ == "__main__":
+    run_cli()

pyhabitat/__main__stable.py

@@ -0,0 +1,72 @@
+#from .cli import run_cli
+
+from .environment import (
+    in_repl,
+    on_termux,
+    on_windows,
+    on_apple,
+    on_linux,
+    on_ish_alpine,
+    on_android,
+    on_freebsd,
+    is_elf,
+    is_windows_portable_executable,
+    is_macos_executable,
+    is_pyz,
+    is_pipx,
+    is_python_script,
+    as_frozen,
+    as_pyinstaller,
+    interp_path,
+    tkinter_is_available,
+    matplotlib_is_available_for_gui_plotting,
+    matplotlib_is_available_for_headless_image_export,
+    web_browser_is_available,
+    interactive_terminal_is_available
+)
+
+def main():
+    print("PyHabitat Environment Report")
+    print("===========================")
+    print("\nInterpreter Checks // Based on sys.executable()")
+    print("-----------------------------")
+    print(f"interp_path(): {interp_path()}")
+    print(f"is_elf(interp_path()): {is_elf(interp_path())}")
+    print(f"is_windows_portable_executable(interp_path()): {is_windows_portable_executable(interp_path())}")
+    print(f"is_macos_executable(interp_path()): {is_macos_executable(interp_path())}")
+    print(f"is_pyz(interp_path()): {is_pyz(interp_path())}")
+    print(f"is_pipx(interp_path()): {is_pipx(interp_path())}")
+    print(f"is_python_script(interp_path()): {is_python_script(interp_path())}")
+    print("\nCurrent Environment Check // Based on sys.argv[0]")
+    print("-----------------------------")
+    print(f"is_elf(): {is_elf()}")
+    print(f"is_windows_portable_executable(): {is_windows_portable_executable()}")
+    print(f"is_macos_executable(): {is_macos_executable()}")
+    print(f"is_pyz(): {is_pyz()}")
+    print(f"is_pipx(): {is_pipx()}")
+    print(f"is_python_script(): {is_python_script()}")
+    print(f"\nCurrent Build Checks // Based on hasattr(sys,..) and getattr(sys,..)")
+    print("------------------------------")
+    print(f"in_repl(): {in_repl()}")
+    print(f"as_frozen(): {as_frozen()}")
+    print(f"as_pyinstaller(): {as_pyinstaller()}")
+    print("\nOperating System Checks // Based on platform.system()")
+    print("------------------------------")
+    print(f"on_termux(): {on_termux()}")
+    print(f"on_windows(): {on_windows()}")
+    print(f"on_apple(): {on_apple()}")
+    print(f"on_linux(): {on_linux()}")
+    print(f"on_ish_alpine(): {on_ish_alpine()}")
+    print(f"on_android(): {on_android()}")
+    print(f"on_freebsd(): {on_freebsd()}")
+    print("\nCapability Checks")
+    print("-------------------------")
+    print(f"tkinter_is_available(): {tkinter_is_available()}")
+    print(f"matplotlib_is_available_for_gui_plotting(): {matplotlib_is_available_for_gui_plotting()}")
+    print(f"matplotlib_is_available_for_headless_image_export(): {matplotlib_is_available_for_headless_image_export()}")
+    print(f"web_browser_is_available(): {web_browser_is_available()}")
+    print(f"interactive_terminal_is_available(): {interactive_terminal_is_available()}")
+
+if __name__ == "__main__":
+    main()
+    #run_cli()

pyhabitat/cli.py

@@ -0,0 +1,22 @@
+import argparse
+from pathlib import Path
+from . import main
+
+def run_cli():
+    """Parse CLI arguments and run the pyhabitat environment report."""
+    parser = argparse.ArgumentParser(
+        description="PyHabitat: Python environment and build introspection"
+    )
+    parser.add_argument(
+        "--path",
+        type=str,
+        default=None,
+        help="Path to a script or binary to inspect (defaults to sys.argv[0])",
+    )
+    parser.add_argument(
+        "--debug",
+        action="store_true",
+        help="Enable verbose debug output",
+    )
+    args = parser.parse_args()
+    main(path=Path(args.path) if args.path else None, debug=args.debug)

pyhabitat/environment.py

@@ -13,12 +13,40 @@ from pathlib import Path
 import subprocess
 import io
 import zipfile
+import logging
+
+__all__ = [
+    'matplotlib_is_available_for_gui_plotting',
+    'matplotlib_is_available_for_headless_image_export',
+    'tkinter_is_available',
+    'on_termux',
+    'on_freebsd',
+    'on_linux',
+    'on_android',
+    'on_windows',
+    'on_apple',
+    'on_ish_alpine',
+    'as_pyinstaller',
+    'as_frozen',
+    'is_elf',
+    'is_pyz',
+    'is_windows_portable_executable',
+    'is_macos_executable',
+    'is_pipx',
+    'interactive_terminal_is_available',
+    'web_browser_is_available',
+    'edit_textfile',
+    'in_repl',
+    'interp_path',
+    'main',
+]
 
 # Global cache for tkinter and matplotlib (mpl) availability
 _TKINTER_AVAILABILITY: bool | None = None
 _MATPLOTLIB_EXPORT_AVAILABILITY: bool | None = None
 _MATPLOTLIB_WINDOWED_AVAILABILITY: bool | None = None
 
+
 # --- GUI CHECKS ---
 def matplotlib_is_available_for_gui_plotting(termux_has_gui=False):
     """Check if Matplotlib is available AND can use a GUI backend for a popup window."""
@@ -29,7 +57,7 @@ def matplotlib_is_available_for_gui_plotting(termux_has_gui=False):
 
     # 1. Termux exclusion check (assume no X11/GUI)
     # Exclude Termux UNLESS the user explicitly provides termux_has_gui=True.
-    if is_termux() and not termux_has_gui: 
+    if on_termux() and not termux_has_gui: 
         _MATPLOTLIB_WINDOWED_AVAILABILITY = False
         return False
     
@@ -118,7 +146,7 @@ def tkinter_is_available() -> bool:
         return False
 
 # --- ENVIRONMENT AND OPERATING SYSTEM CHECKS ---
-def is_termux() -> bool:
+def on_termux() -> bool:
     """Detect if running in Termux environment on Android, based on Termux-specific environmental variables."""
     
     if platform.system() != 'Linux':
@@ -145,22 +173,22 @@ def is_termux() -> bool:
     
     return False
 
-def is_freebsd() -> bool:
+def on_freebsd() -> bool:
     """Detect if running on FreeBSD."""
     return platform.system() == 'FreeBSD'
 
-def is_linux():
+def on_linux():
     """Detect if running on Linux."""
     return platform.system() == 'Linux' 
 
-def is_android() -> bool:
+def on_android() -> bool:
     """
     Detect if running on Android.
     
-    Note: The is_termux() function is more robust and safe for Termux.
-    Checking for Termux with is_termux() does not require checking for Android with is_android().
+    Note: The on_termux() function is more robust and safe for Termux.
+    Checking for Termux with on_termux() does not require checking for Android with on_android().
 
-    is_android() will be True on:   
+    on_android() will be True on:   
         - Sandboxed IDE's:
             - Pydroid3
             - QPython
@@ -170,7 +198,7 @@ def is_android() -> bool:
             - UserLand
             - AnLinux
 
-    is_android() will be False on:
+    on_android() will be False on:
         - Full Virtual Machines:
             - VirtualBox
             - VMware
@@ -181,15 +209,15 @@ def is_android() -> bool:
         return False
     return "android" in platform.platform().lower()
 
-def is_windows() -> bool:
+def on_windows() -> bool:
     """Detect if running on Windows."""
     return platform.system() == 'Windows'
 
-def is_apple() -> bool:
+def on_apple() -> bool:
     """Detect if running on Apple."""
     return platform.system() == 'Darwin'
 
-def is_ish_alpine() -> bool:
+def on_ish_alpine() -> bool:
     """Detect if running in iSH Alpine environment on iOS."""
     # platform.system() usually returns 'Linux' in iSH
 
@@ -208,16 +236,29 @@ def is_ish_alpine() -> bool:
     
     return False
 
+def in_repl() -> bool:
+    """
+    Detects if the code is running in the Python interactive REPL (e.g., when 'python' is typed in a console).
+
+    This function specifically checks for the Python REPL by verifying the presence of the interactive
+    prompt (`sys.ps1`). It returns False for other interactive terminal scenarios, such as running a
+    PyInstaller binary in a console.
+
+    Returns:
+        bool: True if running in the Python REPL; False otherwise.
+    """
+    return hasattr(sys, 'ps1')
+
 
 # --- BUILD AND EXECUTABLE CHECKS ---
     
-def is_pyinstaller():
+def as_pyinstaller():
     """Detects if the Python script is running as a 'frozen' in the course of generating a PyInstaller binary executable."""
     # If the app is frozen AND has the PyInstaller-specific temporary folder path
-    return is_frozen() and hasattr(sys, '_MEIPASS')
+    return as_frozen() and hasattr(sys, '_MEIPASS')
 
 # The standard way to check for a frozen state:
-def is_frozen():
+def as_frozen():
     """
     Detects if the Python script is running as a 'frozen' (standalone) 
     executable created by a tool like PyInstaller, cx_Freeze, or Nuitka.
@@ -235,109 +276,78 @@ def is_frozen():
     """
     return getattr(sys, 'frozen', False)
 
-def is_elf(exec_path : Path = None, debug=False) -> bool:
+# --- Binary Characteristic Checks ---
+def is_elf(exec_path: Path | str | None = None, debug: bool = False) -> bool:
     """Checks if the currently running executable (sys.argv[0]) is a standalone PyInstaller-built ELF binary."""
     # If it's a pipx installation, it is not the monolithic binary we are concerned with here.
-    
-    if exec_path is None:    
-        exec_path = Path(sys.argv[0]).resolve()
-    if debug:
-        print(f"exec_path = {exec_path}")
-    if is_pipx():
+    exec_path, is_valid = _check_executable_path(exec_path, debug)
+    if not is_valid:
         return False
     
-    # Check if the file exists and is readable
-    if not exec_path.is_file():
-        return False
-        
     try:
         # Check the magic number: The first four bytes of an ELF file are 0x7f, 'E', 'L', 'F' (b'\x7fELF').
         # This is the most reliable way to determine if the executable is a native binary wrapper (like PyInstaller's).
         with open(exec_path, 'rb') as f:
             magic_bytes = f.read(4)
-        
+        if debug:
+            logging.debug(f"Magic bytes: {magic_bytes}")
         return magic_bytes == b'\x7fELF'
     except Exception:
-        # Handle exceptions like PermissionError, IsADirectoryError, etc.
+        if debug:
+            logging.debug("False (Exception during file check)")
         return False
     
-def is_pyz(exec_path: Path=None, debug=False) -> bool:
+def is_pyz(exec_path: Path | str | None = None, debug: bool = False) -> bool:
     """Checks if the currently running executable (sys.argv[0]) is a PYZ zipapp ."""
+
     # If it's a pipx installation, it is not the monolithic binary we are concerned with here.
-    if exec_path is None:    
-        exec_path = Path(sys.argv[0]).resolve()
-    if debug:
-        print(f"exec_path = {exec_path}")
-    
-    if is_pipx():
+    exec_path, is_valid = _check_executable_path(exec_path, debug)
+    if not is_valid:
         return False
     
     # Check if the extension is PYZ
     if not str(exec_path).endswith(".pyz"):
+        if debug:
+            logging.debug("False (Not a .pyz file)")
         return False
-    
-    if not _check_if_zip():
+
+    if not _check_if_zip(exec_path):
+        if debug:
+            logging.debug("False (Not a valid ZIP file)")
         return False
 
-def is_windows_portable_executable(exec_path: Path = None, debug=False) -> bool:
+    return True
+
+
+def is_windows_portable_executable(exec_path: Path | str | None = None, debug: bool = False) -> bool:
     """
-    Checks if the currently running executable (sys.argv[0]) is a 
-    Windows Portable Executable (PE) binary, and explicitly excludes 
-    pipx-managed environments.
+    Checks if the specified path or sys.argv[0] is a Windows Portable Executable (PE) binary.
     Windows Portable Executables include .exe, .dll, and other binaries.
     The standard way to check for a PE is to look for the MZ magic number at the very beginning of the file.
     """
-    # 1. Determine execution path
-    if exec_path is None:
-        exec_path = Path(sys.argv[0]).resolve()
-
-    if debug:
-        print(f"DEBUG: Checking executable path: {exec_path}")
-
-    # 2. Exclude pipx environments immediately
-    if is_pipx():
-        if debug: print("DEBUG: is_exe_non_pipx: False (is_pipx is True)")
-        return False
-
-    # 3. Perform file checks
-    if not exec_path.is_file():
-        if debug: print("DEBUG: is_exe_non_pipx: False (Not a file)")
+    exec_path, is_valid = _check_executable_path(exec_path, debug)
+    if not is_valid:
         return False
-
     try:
-        # Check the magic number: All Windows PE files (EXE, DLL, etc.) 
-        # start with the two-byte header b'MZ' (for Mark Zbikowski).
         with open(exec_path, 'rb') as f:
             magic_bytes = f.read(2)
-
-        is_pe = magic_bytes == b'MZ'
-        
-        if debug: 
-            print(f"DEBUG: Magic bytes: {magic_bytes}")
-            print(f"DEBUG: is_exe_non_pipx: {is_pe} (Non-pipx check)")
-            
-        return is_pe
-        
+        if debug:
+            logging.debug(f"Magic bytes: {magic_bytes}")
+        return magic_bytes == b'MZ'
     except Exception as e:
-        if debug: print(f"DEBUG: is_exe_non_pipx: Error during file check: {e}")
-        # Handle exceptions like PermissionError, IsADirectoryError, etc.
+        if debug:
+            logging.debug(f"False (Error during file check: {e})")
         return False
-    
-def is_macos_executable(exec_path: Path = None, debug=False) -> bool:
+        
+def is_macos_executable(exec_path: Path | str | None = None, debug: bool = False) -> bool:
     """
     Checks if the currently running executable is a macOS/Darwin Mach-O binary, 
     and explicitly excludes pipx-managed environments.
     """
-    if exec_path is None:
-        exec_path = Path(sys.argv[0]).resolve()
-
-    if is_pipx():
-        if debug: print("DEBUG: is_macos_executable: False (is_pipx is True)")
+    exec_path, is_valid = _check_executable_path(exec_path, debug)
+    if not is_valid:
         return False
         
-    if not exec_path.is_file():
-        return False
-
     try:
         # Check the magic number: Mach-O binaries start with specific 4-byte headers.
         # Common ones are: b'\xfe\xed\xfa\xce' (32-bit) or b'\xfe\xed\xfa\xcf' (64-bit)
@@ -355,68 +365,128 @@ def is_macos_executable(exec_path: Path = None, debug=False) -> bool:
         is_macho = magic_bytes in MACHO_MAGIC
         
         if debug: 
-            print(f"DEBUG: is_macos_executable: {is_macho} (Non-pipx check)")
+            logging.debug(f"Magic bytes: {magic_bytes}")
             
         return is_macho
         
     except Exception:
+        if debug:
+            logging.debug("False (Exception during file check)")
         return False
     
-def is_pipx(debug=False) -> bool:
+def is_pipx(exec_path: Path | str | None = None, debug: bool = False) -> bool:
     """Checks if the executable is running from a pipx managed environment."""
-    try:
-        # Helper for case-insensitivity on Windows
-        def normalize_path(p: Path) -> str:
-            return str(p).lower()
-
-        exec_path = Path(sys.argv[0]).resolve()
+    exec_path, is_valid = _check_executable_path(exec_path, debug, check_pipx=False)
+    if not is_valid:
+        return False
         
-        # This is the path to the interpreter running the script (e.g., venv/bin/python)
-        # In a pipx-managed execution, this is the venv python.
+    try:
         interpreter_path = Path(sys.executable).resolve()
         pipx_bin_path, pipx_venv_base_path = _get_pipx_paths()
         # Normalize paths for comparison
-        norm_exec_path = normalize_path(exec_path)
-        norm_interp_path = normalize_path(interpreter_path)
+        norm_exec_path = str(exec_path).lower()
+        norm_interp_path = str(interpreter_path).lower()
 
         if debug:
-            # --- DEBUGGING OUTPUT ---
-            print(f"DEBUG: EXEC_PATH:      {exec_path}")
-            print(f"DEBUG: INTERP_PATH:    {interpreter_path}")
-            print(f"DEBUG: PIPX_BIN_PATH:  {pipx_bin_path}")
-            print(f"DEBUG: PIPX_VENV_BASE: {pipx_venv_base_path}")
-            print(f"DEBUG: Check B result: {normalize_path(interpreter_path).startswith(normalize_path(pipx_venv_base_path))}")
-        # ------------------------
-        
-        # 1. Signature Check (Most Robust): Look for the unique 'pipx/venvs' string.
-        # This is a strong check for both the executable path (your discovery) 
-        # and the interpreter path (canonical venv location).
+            logging.debug(f"EXEC_PATH: {exec_path}")
+            logging.debug(f"INTERP_PATH: {interpreter_path}")
+            logging.debug(f"PIPX_BIN_PATH: {pipx_bin_path}")
+            logging.debug(f"PIPX_VENV_BASE: {pipx_venv_base_path}")
+            logging.debug(f"Check B result: {norm_interp_path.startswith(str(pipx_venv_base_path).lower())}")
+
         if "pipx/venvs" in norm_exec_path or "pipx/venvs" in norm_interp_path:
-            if debug: print("is_pipx: True (Signature Check)")
+            if debug:
+                logging.debug("True (Signature Check)")
             return True
 
-        # 2. Targeted Venv Check: The interpreter's path starts with the PIPX venv base.
-        # This is a canonical check if the signature check is somehow missed.
-        if norm_interp_path.startswith(normalize_path(pipx_venv_base_path)):
-            if debug: print("is_pipx: True (Interpreter Base Check)")
+        if norm_interp_path.startswith(str(pipx_venv_base_path).lower()):
+            if debug:
+                logging.debug("True (Interpreter Base Check)")
             return True
-        
-        # 3. Targeted Executable Check: The executable's resolved path starts with the PIPX venv base.
-        # This is your key Termux discovery, confirming the shim resolves into the venv.
-        if norm_exec_path.startswith(normalize_path(pipx_venv_base_path)):
-             if debug: print("is_pipx: True (Executable Base Check)")
-             return True
 
-        if debug: print("is_pipx: False")
+        if norm_exec_path.startswith(str(pipx_venv_base_path).lower()):
+            if debug:
+                logging.debug("True (Executable Base Check)")
+            return True
+
+        if debug:
+            logging.debug("False")
+        return False
+    except Exception:
+        if debug:
+            logging.debug("False (Exception during pipx check)")
         return False
+        if debug:
+            logging.debug(f"EXEC_PATH: {exec_path}")
+            logging.debug(f"INTERP_PATH: {interpreter_path}")
+            logging.debug(f"PIPX_BIN_PATH: {pipx_bin_path}")
+            logging.debug(f"PIPX_VENV_BASE: {pipx_venv_base_path}")
+            logging.debug(f"Check B result: {norm_interp_path.startswith(str(pipx_venv_base_path).lower())}")
+
+        if "pipx/venvs" in norm_exec_path or "pipx/venvs" in norm_interp_path:
+            if debug:
+                logging.debug("True (Signature Check)")
+            return True
+
+        if norm_interp_path.startswith(str(pipx_venv_base_path).lower()):
+            if debug:
+                logging.debug("True (Interpreter Base Check)")
+            return True
 
+        if norm_exec_path.startswith(str(pipx_venv_base_path).lower()):
+            if debug:
+                logging.debug("True (Executable Base Check)")
+            return True
+
+        if debug:
+            logging.debug("False")
+        return False
     except Exception:
-        # Fallback for unexpected path errors
+        if debug:
+            logging.debug("False (Exception during pipx check)")
         return False
-    
+def is_python_script(path: Path | str | None = None, debug: bool = False) -> bool:
+    """
+    Checks if the specified path or running script is a Python source file (.py).
 
+    By default, checks the running script (`sys.argv[0]`). If a specific `path` is
+    provided, checks that path instead. Uses `Path.resolve()` for stable path handling.
 
-# --- TTY CHECK ---
+    Args:
+        path: Optional; path to the file to check (str or Path). If None, defaults to `sys.argv[0]`.
+        debug: If True, prints the path being checked.
+
+    Returns:
+        bool: True if the specified or default path is a Python source file (.py); False otherwise.
+    """
+    exec_path, is_valid = _check_executable_path(path, debug, check_pipx=False)
+    if not is_valid:
+        return False
+    return exec_path.suffix.lower() == '.py'    
+
+# --- Interpreter Check ---
+
+def interp_path(print_path: bool = False) -> str:
+    """
+    Returns the path to the Python interpreter binary and optionally prints it.
+
+    This function wraps `sys.executable` to provide the path to the interpreter
+    (e.g., '/data/data/com.termux/files/usr/bin/python3' in Termux or the embedded
+    interpreter in a frozen executable). If the path is empty (e.g., in some embedded
+    or sandboxed environments), an empty string is returned.
+
+    Args:
+        print_path: If True, prints the interpreter path to stdout.
+
+    Returns:
+        str: The path to the Python interpreter binary, or an empty string if unavailable.
+    """
+    path = sys.executable
+    if print_path:
+        print(f"Python interpreter path: {path}")
+    return path
+
+# --- TTY Check ---
 def interactive_terminal_is_available():
     """
     Check if the script is running in an interactive terminal. 
@@ -440,7 +510,7 @@ def web_browser_is_available() -> bool:
     except webbrowser.Error:
         # Fallback needed. Check for external launchers.
         # 2. Termux specific check
-        if is_termux() and shutil.which("termux-open-url"):
+        if on_termux() and shutil.which("termux-open-url"):
             return True
         # 3. General Linux check
         if shutil.which("xdg-open"):
@@ -448,34 +518,42 @@ def web_browser_is_available() -> bool:
         return False
     
 # --- LAUNCH MECHANISMS BASED ON ENVIRONMENT ---
-def edit_textfile(filepath) -> None:
-#def open_text_file_for_editing(filepath):
+def edit_textfile(path: Path | str | None = None) -> None:
+#def open_text_file_for_editing(path): # defunct function name as of 1.0.16
     """
     Opens a file with the environment's default application (Windows, Linux, macOS)
     or a guaranteed console editor (nano) in constrained environments (Termux, iSH)
     after ensuring line-ending compatibility.
+
+    This function is known to fail on PyDroid3, where on_linus() is True but xdg-open 
+    is not available.
     """
+    if path is None:
+        return
+    
+    path = Path(path).resolve()
+
     try:
-        if is_windows():
-            os.startfile(filepath)
-        elif is_termux():
+        if on_windows():
+            os.startfile(path)
+        elif on_termux():
     	    # Install dependencies if missing (Termux pkg returns non-zero if already installed, so no check=True)
     	    subprocess.run(['pkg','install', 'dos2unix', 'nano'], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
-    	    _run_dos2unix(filepath)
-    	    subprocess.run(['nano', filepath])
-        elif is_ish_alpine():
+    	    _run_dos2unix(path)
+    	    subprocess.run(['nano', path])
+        elif on_ish_alpine():
             # Install dependencies if missing (apk returns 0 if already installed, so check=True is safe)
     	    subprocess.run(['apk','add', 'dos2unix'], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, check=True)
     	    subprocess.run(['apk','add', 'nano'], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, check=True)
-    	    _run_dos2unix(filepath)
-    	    subprocess.run(['nano', filepath])
+    	    _run_dos2unix(path)
+    	    subprocess.run(['nano', path])
     	# --- Standard Unix-like Systems (Conversion + Default App) ---
-        elif is_linux():
-    	    _run_dos2unix(filepath) # Safety conversion for user-defined console apps
-    	    subprocess.run(['xdg-open', filepath])
-        elif is_apple():
-    	    _run_dos2unix(filepath) # Safety conversion for user-defined console apps
-    	    subprocess.run(['open', filepath])
+        elif on_linux():
+    	    _run_dos2unix(path) # Safety conversion for user-defined console apps
+    	    subprocess.run(['xdg-open', path])
+        elif on_apple():
+    	    _run_dos2unix(path) # Safety conversion for user-defined console apps
+    	    subprocess.run(['open', path])
         else:
     	    print("Unsupported operating system.")
     except Exception as e:
@@ -484,14 +562,18 @@ def edit_textfile(filepath) -> None:
     """Why Not Use check=True on Termux:
     The pkg utility in Termux is a wrapper around Debian's apt. When you run pkg install <package>, if the package is already installed, the utility often returns an exit code of 100 (or another non-zero value) to indicate that no changes were made because the package was already present.
     """
-    
-def _run_dos2unix(filepath):
+
+# --- Helper Functions ---    
+def _run_dos2unix(path: Path | str | None = None):
     """Attempt to run dos2unix, failing silently if not installed."""
+    
+    path = Path(path).resolve()
+
     try:
         # We rely on shutil.which not being needed, as this is a robust built-in utility on most targets
         # The command won't raise an exception unless the process itself fails, not just if the utility isn't found.
         # We also don't use check=True here to allow silent failure if the utility is missing (e.g., minimalist Linux).
-        subprocess.run(['dos2unix', filepath], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+        subprocess.run(['dos2unix', path], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
     except FileNotFoundError:
         # This will be raised if 'dos2unix' is not on the system PATH
         pass 
@@ -526,11 +608,111 @@ def _get_pipx_paths():
     return pipx_bin_path, pipx_venv_base.resolve()
 
 
-def _check_if_zip(file_path: str | Path) -> bool:
+def _check_if_zip(path: Path | str | None) -> bool:
     """Checks if the file at the given path is a valid ZIP archive."""
+    if path is None:
+        return False
+    path = Path(path).resolve()
+
     try:
-        return zipfile.is_zipfile(file_path)
+        return zipfile.is_zipfile(path)
     except Exception:
         # Handle cases where the path might be invalid, or other unexpected errors
         return False
-        
+
+def _check_executable_path(exec_path: Path | str | None, debug: bool = False, check_pipx: bool = True) -> tuple[Path | None, bool]:
+    """Helper function to resolve executable path and perform common checks."""
+    if exec_path is None:
+        exec_path = Path(sys.argv[0]).resolve() if sys.argv[0] and sys.argv[0] != '-c' else None
+    else:
+        exec_path = Path(exec_path).resolve()
+
+    if debug:
+        logging.debug(f"Checking executable path: {exec_path}")
+
+    if exec_path is None:
+        if debug:
+            logging.debug("False (No valid path)")
+        return None, False
+
+    if check_pipx and is_pipx(exec_path, debug):
+        if debug:
+            logging.debug("False (is_pipx is True)")
+        return exec_path, False
+
+    if not exec_path.is_file():
+        if debug:
+            logging.debug("False (Not a file)")
+        return exec_path, False
+
+    return exec_path, True        
+
+# --- Main Function for report and CLI compatibility ---
+
+def main(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("PyHabitat Environment Report")
+    print("===========================")
+    print("\nCurrent Build Checks // Based on hasattr(sys,..) and getattr(sys,..)")
+    print("------------------------------")
+    print(f"in_repl(): {in_repl()}")
+    print(f"as_frozen(): {as_frozen()}")
+    print(f"as_pyinstaller(): {as_pyinstaller()}")
+    print("\nOperating System Checks // Based on platform.system()")
+    print("------------------------------")
+    print(f"on_termux(): {on_termux()}")
+    print(f"on_windows(): {on_windows()}")
+    print(f"on_apple(): {on_apple()}")
+    print(f"on_linux(): {on_linux()}")
+    print(f"on_ish_alpine(): {on_ish_alpine()}")
+    print(f"on_android(): {on_android()}")
+    print(f"on_freebsd(): {on_freebsd()}")
+    print("\nCapability Checks")
+    print("-------------------------")
+    print(f"tkinter_is_available(): {tkinter_is_available()}")
+    print(f"matplotlib_is_available_for_gui_plotting(): {matplotlib_is_available_for_gui_plotting()}")
+    print(f"matplotlib_is_available_for_headless_image_export(): {matplotlib_is_available_for_headless_image_export()}")
+    print(f"web_browser_is_available(): {web_browser_is_available()}")
+    print(f"interactive_terminal_is_available(): {interactive_terminal_is_available()}")
+    print("\nInterpreter Checks // Based on sys.executable()")
+    print("-----------------------------")
+    print(f"interp_path(): {interp_path()}")
+    print(f"is_elf(interp_path()): {is_elf(interp_path(), debug=debug)}")
+    print(f"is_windows_portable_executable(interp_path()): {is_windows_portable_executable(interp_path(), debug=debug)}")
+    print(f"is_macos_executable(interp_path()): {is_macos_executable(interp_path(), debug=debug)}")
+    print(f"is_pyz(interp_path()): {is_pyz(interp_path(), debug=debug)}")
+    print(f"is_pipx(interp_path()): {is_pipx(interp_path(), debug=debug)}")
+    print(f"is_python_script(interp_path()): {is_python_script(interp_path(), debug=debug)}")
+    print("\nCurrent Environment Check // 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()
+    logging.debug(f"Script path resolved: {script_path}")
+    if script_path is not None:
+        print(f"is_elf(): {is_elf(script_path, debug=debug)}")
+        print(f"is_windows_portable_executable(): {is_windows_portable_executable(script_path, debug=debug)}")
+        print(f"is_macos_executable(): {is_macos_executable(script_path, debug=debug)}")
+        print(f"is_pyz(): {is_pyz(script_path, debug=debug)}")
+        print(f"is_pipx(): {is_pipx(script_path, debug=debug)}")
+        print(f"is_python_script(): {is_python_script(script_path, debug=debug)}")
+    else:
+        print("script_path is None")

{pyhabitat-1.0.16.dist-info → pyhabitat-1.0.18.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyhabitat
-Version: 1.0.16
+Version: 1.0.18
 Summary: A lightweight library for detecting system environment, GUI, and build properties.
 Author-email: George Clayton Bennett <george.bennett@memphistn.gov>
 License-Expression: MIT
@@ -8,7 +8,7 @@ Keywords: environment,os-detection,gui,build-system
 Classifier: Programming Language :: Python :: 3
 Classifier: Operating System :: OS Independent
 Classifier: Topic :: System :: Systems Administration
-Requires-Python: >=3.8
+Requires-Python: >=3.7
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Dynamic: license-file
@@ -59,11 +59,11 @@ Ultimately, [City-of-Memphis-Wastewater](https://github.com/City-of-Memphis-Wast
 
   * **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 built by tools like PyInstaller, and, crucially, correct identification and exclusion of pipx-managed virtual environments, which also user binaries that could conflate the check.
-  * **Executable Type Inspection:** Uses file magic numbers (ELF and MZ) to confirm if the running script is a monolithic, frozen binary (non-pipx).
+  * **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>
@@ -75,26 +75,31 @@ Key question: "What is this running on?"
 
 | Function | Description |
 | :--- | :--- |
-| `is_windows()` | Returns `True` on Windows. |
-| `is_apple()` | Returns `True` on macOS (Darwin). |
-| `is_linux()` | Returns `True` on Linux in general. |
-| `is_termux()` | Returns `True` if running in the Termux Android environment. |
-| `is_ish_alpine()` | Returns `True` if running in the iSH Alpine Linux iOS emulator. |
-| `is_android()` | Returns `True` on any Android-based Linux environment. |
+| `on_windows()` | Returns `True` on Windows. |
+| `on_apple()` | Returns `True` on macOS (Darwin). |
+| `on_linux()` | Returns `True` on Linux in general. |
+| `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. |
+| `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?"
+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 |
 | :--- | :--- |
-| `is_frozen()` | Returns `True` if the script is running as a standalone executable (any bundler). |
-| `is_pyinstaller()` | Returns `True` if the script is_frozen() and was generated by Pyinstaller (has MEI). |
-| `is_pipx()` | Returns `True` if running from a pipx managed virtual environment. |
-| `is_elf()` | Checks if the executable is an ELF binary (Linux standalone executable), excluding pipx. |
-| `is_windows_portable_executable()` | Checks if the executable is a Windows PE binary (MZ header), excluding pipx. |
-| `is_macos_executable()` | Checks if the executable is a macOS/Darwin Mach-O binary, excluding pipx. || `is_macos_executable()` | Checks if the executable is a macOS/Darwin Mach-O binary, excluding pipx. |
-
+| `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_macos_executable(path=None)` | Returns `True` if the script or specified path is a macOS Mach-O binary (non-pipx). |
 
 ### Capability Checking
 
@@ -103,16 +108,18 @@ 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. |
+| `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). 	|
 
-### Actions
+### Utility
 
 | Function | Description |
 | :--- | :--- |
-| `edit_textfile()` | Smoothly opens a text file for editing (for configuration editing prompted by a CLI flag). |
+| `edit_textfile(path)` | Opens a text file for editing using the default editor (Windows, Linux, macOS) or nano in Termux/iSH. In REPL mode, prints an error. Path argument (str or Path) uses Path.resolve() for stability. |
+| `interp_path(print_path=False)` | Returns the path to the Python interpreter binary (sys.executable). Optionally prints the path. Returns empty string if unavailable. |
+| `main()` | 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>
 
@@ -123,39 +130,57 @@ Key Question: "What could I do next?"
 
 The module exposes all detection functions directly for easy access.
 
-### 0\. Current Use
+### 0\. Example of PyHabitat in Action
 
 The `pipeline-eds` package uses the `pyhabitat` library to handle [configuration](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/pipeline/blob/main/src/pipeline/cli.py), among other things.
 
-### 1\. Checking Environment and Build Type
+### 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
-from pyhabitat import is_termux, is_windows, is_pipx, is_frozen
+# In the Python REPL
+import pyhabitat as ph
+ph.main()
+```
+
+### 2\. Checking Environment and Build Type
+
+```python
+from pyhabitat import on_termux, on_windows, is_pipx, is_python_script, as_frozen
 
 if is_pipx():
     print("Running inside a pipx virtual environment. This is not a standalone binary.")
 
-elif is_frozen():
+if as_frozen():
     print("Running as a frozen executable (PyInstaller, cx_Freeze, etc.).")
 
-elif is_termux(): 
+if is_python_script():
+    print("Running as a Python source script (.py).")
+
+if on_termux(): 
 	# Expected cases: 
 	#- pkg install python-numpy python-cryptography
-	#- Avoiding matplotlib unless the user explicitly confirms that termux_has_gui=False in matplotlib_is_available_for_gui_plotting(termux_has_gui=False).
+	#- Avoiding matplotlib unless the user explicitly sets termux_has_gui=True in matplotlib_is_available_for_gui_plotting().
 	#- Auto-selection of 'termux-open-url' and 'xdg-open' in logic.
 	#- Installation on the system, like orchestrating the construction of Termux Widget entries in ~/.shortcuts.
     print("Running in the Termux environment on Android.")
     
-elif is_windows():
+if on_windows():
     print("Running on Windows.")
 ```
 
-### 2\. Checking GUI and Plotting Availability
+### 3\. Checking GUI and Plotting Availability
 
 Use these functions to determine if you can show an interactive plot or if you must save an image file.
 
 ```python
-from pyhabitat import matplotlib_is_available_for_gui_plotting, matplotlib_is_available_for_headless_image_export, 
+from pyhabitat import matplotlib_is_available_for_gui_plotting, matplotlib_is_available_for_headless_image_export
 
 if matplotlib_is_available_for_gui_plotting():
     # We can safely call plt.show()
@@ -173,13 +198,16 @@ else:
     print("Matplotlib is not installed or the environment is too restrictive for plotting.")
 ```
 
-### 3\. Text Editing
+### 4\. Text Editing
 
-Use this function to smoothly open a text file for 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
-edit_textfile(filepath=Path('./config.json'))
+from pathlib import Path
+import pyhabitat as ph
+
+ph.edit_textfile(path=Path('./config.json'))
 ```
 </details>
 

pyhabitat-1.0.18.dist-info/RECORD

@@ -0,0 +1,11 @@
+pyhabitat/__init__.py,sha256=GcpHBpfEer9O9dKBUREU1RTd5w0im9ph5ew4bs7jOvY,1228
+pyhabitat/__main__.py,sha256=hhH17lkw-ZalKp9NolnPGwW0KYxbXirspWvhBKNyBks,67
+pyhabitat/__main__stable.py,sha256=UACpHLrr_Rmf0L5dJCEae6kFzLn7dqCqIri68IBnb10,2910
+pyhabitat/cli.py,sha256=vuRczazuumIaJl4Td2VvCR5lXcKKNH90V8Yx0KZUJck,663
+pyhabitat/environment.py,sha256=7yXMCHvTRkfwwQnsgzrDXPDG9m8h8yhI5oCNlJTHWUA,28026
+pyhabitat-1.0.18.dist-info/licenses/LICENSE,sha256=D4fg30ctUGnCJlWu3ONv5-V8JE1v3ctakoJTcVjsJlg,1072
+pyhabitat-1.0.18.dist-info/METADATA,sha256=Xk4blTODZGW6NiuqN5e33SuePkTb-PnNU5pGGzeHXvs,10733
+pyhabitat-1.0.18.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+pyhabitat-1.0.18.dist-info/entry_points.txt,sha256=409xZ-BrarQJJLtO-aActCGkL0FMhNVi9wsq3u7tRHM,52
+pyhabitat-1.0.18.dist-info/top_level.txt,sha256=zXYK44Qu8EqxUETREvd2diMUaB5JiGRErkwFaoLQnnI,10
+pyhabitat-1.0.18.dist-info/RECORD,,

pyhabitat-1.0.18.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pyhabitat = pyhabitat.cli:run_cli

pyhabitat-1.0.16.dist-info/RECORD

@@ -1,7 +0,0 @@
-pyhabitat/__init__.py,sha256=MiYIzYPqB3o6ZFXQ1C9BV2M2KI17BSq9CA6p8Uc7_h0,1096
-pyhabitat/environment.py,sha256=v9e47TdbtMSiljkjr9-lfdUILQu95HLH0SB6k7QIba0,20757
-pyhabitat-1.0.16.dist-info/licenses/LICENSE,sha256=D4fg30ctUGnCJlWu3ONv5-V8JE1v3ctakoJTcVjsJlg,1072
-pyhabitat-1.0.16.dist-info/METADATA,sha256=APK_RIRIKYUzZ3nuNgcRUvbDhaHZnWXAwvatvPwU_Qg,9001
-pyhabitat-1.0.16.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-pyhabitat-1.0.16.dist-info/top_level.txt,sha256=zXYK44Qu8EqxUETREvd2diMUaB5JiGRErkwFaoLQnnI,10
-pyhabitat-1.0.16.dist-info/RECORD,,