pyhabitat 1.0.16__tar.gz → 1.0.17__tar.gz

{pyhabitat-1.0.16 → pyhabitat-1.0.17}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyhabitat
-Version: 1.0.16
+Version: 1.0.17
 Summary: A lightweight library for detecting system environment, GUI, and build properties.
 Author-email: George Clayton Bennett <george.bennett@memphistn.gov>
 License-Expression: MIT
@@ -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.16 → pyhabitat-1.0.17}/README.md

@@ -44,11 +44,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>
@@ -60,26 +60,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
 
@@ -88,16 +93,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>
 
@@ -108,39 +115,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()
@@ -158,13 +183,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.16 → pyhabitat-1.0.17}/pyhabitat/__init__.py

@@ -4,45 +4,54 @@ 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,
 )
 
+from .__main__ import main
+
 # Optional: Set __all__ for explicit documentation and cleaner imports
 __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-1.0.17/pyhabitat/__main__.py

@@ -0,0 +1,69 @@
+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()

{pyhabitat-1.0.16 → pyhabitat-1.0.17}/pyhabitat/environment.py

@@ -14,6 +14,31 @@ import subprocess
 import io
 import zipfile
 
+__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',
+]
+
 # Global cache for tkinter and matplotlib (mpl) availability
 _TKINTER_AVAILABILITY: bool | None = None
 _MATPLOTLIB_EXPORT_AVAILABILITY: bool | None = None
@@ -29,7 +54,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 +143,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 +170,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 +195,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 +206,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 +233,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,21 +273,26 @@ 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()
+    else:
+        exec_path = Path(exec_path).resolve()
+
     if debug:
-        print(f"exec_path = {exec_path}")
+        print(f"DEBUG: Checking executable path: {exec_path}")
+        
     if is_pipx():
         return False
     
     # Check if the file exists and is readable
     if not exec_path.is_file():
-        return False
-        
+        if debug: print("DEBUG:False (Not a 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).
@@ -261,13 +304,20 @@ def is_elf(exec_path : Path = None, debug=False) -> bool:
         # Handle exceptions like PermissionError, IsADirectoryError, etc.
         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()
+    else:
+        exec_path = Path(exec_path).resolve()
+
     if debug:
-        print(f"exec_path = {exec_path}")
+        print(f"DEBUG: Checking executable path: {exec_path}")
+        
+    if not exec_path.is_file():
+        if debug: print("DEBUG:False (Not a file)")
+        return False
     
     if is_pipx():
         return False
@@ -276,10 +326,10 @@ def is_pyz(exec_path: Path=None, debug=False) -> bool:
     if not str(exec_path).endswith(".pyz"):
         return False
     
-    if not _check_if_zip():
+    if not _check_if_zip(exec_path):
         return False
 
-def is_windows_portable_executable(exec_path: Path = None, debug=False) -> bool:
+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 
@@ -290,18 +340,20 @@ def is_windows_portable_executable(exec_path: Path = None, debug=False) -> bool:
     # 1. Determine execution path
     if exec_path is None:
         exec_path = Path(sys.argv[0]).resolve()
+    else:
+        exec_path = Path(exec_path).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)")
+        if debug: print("DEBUG: 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)")
+        if debug: print("DEBUG:False (Not a file)")
         return False
 
     try:
@@ -314,30 +366,35 @@ def is_windows_portable_executable(exec_path: Path = None, debug=False) -> bool:
         
         if debug: 
             print(f"DEBUG: Magic bytes: {magic_bytes}")
-            print(f"DEBUG: is_exe_non_pipx: {is_pe} (Non-pipx check)")
+            print(f"DEBUG: {is_pe} (Non-pipx check)")
             
         return is_pe
         
     except Exception as e:
-        if debug: print(f"DEBUG: is_exe_non_pipx: Error during file check: {e}")
+        if debug: print(f"DEBUG: Error during file check: {e}")
         # Handle exceptions like PermissionError, IsADirectoryError, etc.
         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()
-
+    else:
+        exec_path = Path(exec_path).resolve()
+    if debug:
+        print(f"DEBUG: Checking executable path: {exec_path}")
+        
     if is_pipx():
         if debug: print("DEBUG: is_macos_executable: False (is_pipx is True)")
         return False
         
     if not exec_path.is_file():
+        if debug: print("DEBUG:False (Not a 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)
@@ -362,15 +419,23 @@ def is_macos_executable(exec_path: Path = None, debug=False) -> bool:
     except Exception:
         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."""
+    if exec_path is None:
+        exec_path = Path(sys.argv[0]).resolve()
+    else:
+        exec_path = Path(exec_path).resolve()
+    if debug:
+        print(f"DEBUG: Checking executable path: {exec_path}")
+        
+    if not exec_path.is_file():
+        if debug: print("DEBUG:False (Not a file)")
+        return False
     try:
         # Helper for case-insensitivity on Windows
         def normalize_path(p: Path) -> str:
             return str(p).lower()
 
-        exec_path = Path(sys.argv[0]).resolve()
-        
         # 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.
         interpreter_path = Path(sys.executable).resolve()
@@ -413,10 +478,54 @@ def is_pipx(debug=False) -> bool:
     except Exception:
         # Fallback for unexpected path errors
         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.
+
+    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.
+    """
+    if path is None:
+        exec_path = Path(sys.argv[0]).resolve()
+    else:
+        exec_path = Path(path).resolve()
+    if debug:
+        print(f"Checking Python script for path: {exec_path}")
+    if not exec_path.is_file():
+        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 ---
+# --- TTY Check ---
 def interactive_terminal_is_available():
     """
     Check if the script is running in an interactive terminal. 
@@ -440,7 +549,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 +557,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:
@@ -485,13 +602,16 @@ def edit_textfile(filepath) -> None:
     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):
+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,10 +646,14 @@ 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

{pyhabitat-1.0.16 → pyhabitat-1.0.17}/pyhabitat.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyhabitat
-Version: 1.0.16
+Version: 1.0.17
 Summary: A lightweight library for detecting system environment, GUI, and build properties.
 Author-email: George Clayton Bennett <george.bennett@memphistn.gov>
 License-Expression: MIT
@@ -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.16 → pyhabitat-1.0.17}/pyhabitat.egg-info/SOURCES.txt

@@ -2,6 +2,7 @@ LICENSE
 README.md
 pyproject.toml
 pyhabitat/__init__.py
+pyhabitat/__main__.py
 pyhabitat/environment.py
 pyhabitat.egg-info/PKG-INFO
 pyhabitat.egg-info/SOURCES.txt

{pyhabitat-1.0.16 → pyhabitat-1.0.17}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pyhabitat"
-version = "1.0.16"
+version = "1.0.17"
 #dynamic = ["version"] # 
 authors = [
   { name="George Clayton Bennett", email="george.bennett@memphistn.gov" },