pyhabitat 0.1.2__tar.gz → 1.0.6__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Potentially problematic release.

This version of pyhabitat might be problematic. Click here for more details.

Files changed (11) hide show
  1. {pyhabitat-0.1.2 → pyhabitat-1.0.6}/PKG-INFO +76 -38
  2. {pyhabitat-0.1.2 → pyhabitat-1.0.6}/README.md +73 -34
  3. {pyhabitat-0.1.2 → pyhabitat-1.0.6}/pyhabitat.egg-info/PKG-INFO +76 -38
  4. {pyhabitat-0.1.2 → pyhabitat-1.0.6}/pyproject.toml +9 -5
  5. {pyhabitat-0.1.2 → pyhabitat-1.0.6}/LICENSE +0 -0
  6. {pyhabitat-0.1.2 → pyhabitat-1.0.6}/pyhabitat/__init__.py +0 -0
  7. {pyhabitat-0.1.2 → pyhabitat-1.0.6}/pyhabitat/environment.py +0 -0
  8. {pyhabitat-0.1.2 → pyhabitat-1.0.6}/pyhabitat.egg-info/SOURCES.txt +0 -0
  9. {pyhabitat-0.1.2 → pyhabitat-1.0.6}/pyhabitat.egg-info/dependency_links.txt +0 -0
  10. {pyhabitat-0.1.2 → pyhabitat-1.0.6}/pyhabitat.egg-info/top_level.txt +0 -0
  11. {pyhabitat-0.1.2 → pyhabitat-1.0.6}/setup.cfg +0 -0
{pyhabitat-0.1.2 → pyhabitat-1.0.6}/PKG-INFO RENAMED
@@ -1,12 +1,11 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: pyhabitat
3
- Version: 0.1.2
4
- Summary: A robust library for detecting system environment, GUI, and build properties.
3
+ Version: 1.0.6
4
+ Summary: A lightweight library for detecting system environment, GUI, and build properties.
5
5
  Author-email: George Clayton Bennett <george.bennett@memphistn.gov>
6
- License: MIT
6
+ License-Expression: MIT
7
7
  Keywords: environment,os-detection,gui,build-system
8
8
  Classifier: Programming Language :: Python :: 3
9
- Classifier: License :: OSI Approved :: MIT License
10
9
  Classifier: Operating System :: OS Independent
11
10
  Classifier: Topic :: System :: Systems Administration
12
11
  Requires-Python: >=3.8
@@ -16,17 +15,31 @@ Dynamic: license-file
16
15
 
17
16
  # pyhabitat 🧭
18
17
 
19
- ## A Robust Environment and Build Introspection Library for Python
18
+ ## An Introspection Library for Python Environments and Builds
20
19
 
21
- **`pyhabitat`** is a focused, lightweight library designed to accurately and securely determine the execution context of a running Python script. It provides definitive checks for the Operating System (OS), common container/emulation environments (Termux, iSH), build states (PyInstaller, pipx), and the availability of GUI backends (Matplotlib, Tkinter).
20
+ **`pyhabitat`** is a **lightweight library for Python build and environment introspection**. It accurately and securely determines the execution context of a running script by providing definitive checks for:
22
21
 
23
- Stop writing verbose `sys.platform` and environment variable checks. Instead, use **`pyhabitat`** to implement architectural logic in your code.
22
+ * **OS and Environments:** Operating Systems and common container/emulation environments (e.g., Termux, iSH).
23
+ * **Build States:** Application build systems (e.g., PyInstaller, pipx).
24
+ * **GUI Backends:** Availability of graphical toolkits (e.g., Matplotlib, Tkinter).
25
+
26
+ Stop writing verbose `sys.platform` and environment variable checks. Use **`pyhabitat`** to implement clean, **architectural logic** based on the execution habitat.
27
+
28
+ This library is especially useful for **leveraging Python in mobile environments** (`Termux` on Android and `iSH` on iOS), which often have particular limitations and require special handling. For example, it helps automate work-arounds like using **localhost plotting** when `matplotlib` is unavailable or **web-based interfaces** when `tkinter` is missing.
29
+
30
+ Our team is fundamentally driven by enabling mobile computing for true utility applications, leveraging environments like Termux (Android) and iSH (iOS). This includes highly practical solutions, such as deploying a lightweight Python web server (e.g., Flask, http.server, FastAPI) directly on a handset, or orchestrating full-stack, utility-grade applications that allow technicians to manage data and systems right from their mobile device in a way that is cross-platform and not overly catered to the App Store.
31
+
32
+ Another key goal of this project is to facilitate the orchestration of wider system installation for **`pipx` CLI tools** for additional touch points, like addition to context menus and widgets.
33
+
34
+ Ultimately, [City-of-Memphis-Wastewater](https://github.com/City-of-Memphis-Wastewater) aims to produce **reference-quality code** for the documented proper approach. We recognize that many people (and bots) are searching for ideal solutions, and our functions are built upon extensive research and testing to go **beyond simple `platform.system()` checks**.
35
+
36
+ ---
24
37
 
25
38
  ## 🚀 Features
26
39
 
27
- * **Definitive Environment Checks:** Accurate detection for Windows, macOS (Apple), Linux, FreeBSD, Android (general), Termux, and iSH (iOS Alpine).
40
+ * **Definitive Environment Checks:** Rigorous checks catered to Termux and iSH (iOS Alpine). Accurate, typical modern detection for Windows, macOS (Apple), Linux, FreeBSD, Android.
28
41
  * **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).
29
- * **Build/Packaging Detection:** Reliable detection of standalone executables built by tools like PyInstaller, and, crucially, correct identification and exclusion of pipx-managed virtual environments.
42
+ * **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.
30
43
  * **Executable Type Inspection:** Uses file magic numbers (ELF and MZ) to confirm if the running script is a monolithic, frozen binary (non-pipx).
31
44
 
32
45
  ## 📦 Installation
@@ -34,6 +47,47 @@ Stop writing verbose `sys.platform` and environment variable checks. Instead, us
34
47
  ```bash
35
48
  pip install pyhabitat
36
49
  ```
50
+ ---
51
+
52
+ ## 📚 API Reference
53
+
54
+ ### OS and Environment
55
+
56
+ | Function | Description |
57
+ | :--- | :--- |
58
+ | `is_windows()` | Returns `True` on Windows. |
59
+ | `is_apple()` | Returns `True` on macOS (Darwin). |
60
+ | `is_linux()` | Returns `True` on Linux in general. |
61
+ | `is_termux()` | Returns `True` if running in the Termux Android environment. |
62
+ | `is_ish_alpine()` | Returns `True` if running in the iSH Alpine Linux iOS emulator. |
63
+ | `is_android()` | Returns `True` on any Android-based Linux environment. |
64
+
65
+ ### Build and Packaging
66
+
67
+ | Function | Description |
68
+ | :--- | :--- |
69
+ | `is_frozen()` | Returns `True` if the script is running as a standalone executable (any bundler). |
70
+ | `is_pipx()` | Returns `True` if running from a pipx managed virtual environment. |
71
+ | `is_elf()` | Checks if the executable is an ELF binary (Linux standalone executable), excluding pipx. |
72
+ | `is_windows_portable_executable()` | Checks if the executable is a Windows PE binary (MZ header), excluding pipx. |
73
+ | `is_macos_executable()` | Checks if the executable is a macOS/Darwin Mach-O binary, excluding pipx. |
74
+
75
+ ### Capabilities
76
+
77
+ | Function | Description |
78
+ | :--- | :--- |
79
+ | `tkinter_is_available()` | Checks if Tkinter is imported and can successfully create a window. |
80
+ | `matplotlib_is_available_for_gui_plotting(termux_has_gui=False)` | Checks for Matplotlib and its TkAgg backend, required for interactive plotting. |
81
+ | `matplotlib_is_available_for_headless_image_export()` | Checks for Matplotlib and its Agg backend, required for saving images without a GUI. |
82
+ | `is_interactive_terminal()` | Checks if standard input and output streams are connected to a TTY (allows safe use of interactive prompts). |
83
+ | `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). |
84
+
85
+ ### Actions
86
+ | Function | Description |
87
+ | :--- | :--- |
88
+ | `open_text_file_in_default_app()` | Smoothly opens a text file for editing (for configuration editing prompted by a CLI flag). |
89
+
90
+ ---
37
91
 
38
92
  ## 💻 Usage Examples
39
93
 
@@ -49,8 +103,13 @@ if is_pipx():
49
103
 
50
104
  elif is_frozen():
51
105
  print("Running as a frozen executable (PyInstaller, cx_Freeze, etc.).")
52
-
106
+
53
107
  elif is_termux():
108
+ # Expected cases:
109
+ #- pkg install python-numpy python-cryptography
110
+ #- Avoiding matplotlib unless the user explicitly confirms that termux_has_gui=False in matplotlib_is_available_for_gui_plotting(termux_has_gui=False).
111
+ #- Auto-selection of 'termux-open-url' and 'xdg-open' in logic.
112
+ #- Installation on the system, like orchestrating the construction of Termux Widget entries in ~/.shortcuts.
54
113
  print("Running in the Termux environment on Android.")
55
114
 
56
115
  elif is_windows():
@@ -80,36 +139,15 @@ else:
80
139
  print("Matplotlib is not installed or the environment is too restrictive for plotting.")
81
140
  ```
82
141
 
83
- ## 📚 API Reference
84
-
85
- ### OS and Environment
86
-
87
- | Function | Description |
88
- | :--- | :--- |
89
- | `is_windows()` | Returns `True` on Windows. |
90
- | `is_apple()` | Returns `True` on macOS (Darwin). |
91
- | `is_linux()` | Returns `True` on Linux in general. |
92
- | `is_termux()` | Returns `True` if running in the Termux Android environment. |
93
- | `is_ish_alpine()` | Returns `True` if running in the iSH Alpine Linux iOS emulator. |
94
- | `is_android()` | Returns `True` on any Android-based Linux environment. |
95
-
96
- ### Build and Packaging
97
-
98
- | Function | Description |
99
- | :--- | :--- |
100
- | `is_frozen()` | Returns `True` if the script is running as a standalone executable (any bundler). |
101
- | `is_pipx()` | Returns `True` if running from a pipx managed virtual environment. |
102
- | `is_elf()` | Checks if the executable is an ELF binary (Linux standalone executable), excluding pipx. |
103
- | `is_windows_portable_executable()` | Checks if the executable is a Windows PE binary (MZ header), excluding pipx. |
142
+ ### 3\. Text Editing
104
143
 
105
- ### Capabilities
144
+ Use this function to smoothly open a text file for editing.
145
+ Ideal use case: Edit a configuration file, if prompted by a CLI command like 'config --textedit'.
106
146
 
107
- | Function | Description |
108
- | :--- | :--- |
109
- | `tkinter_is_available()` | Checks if Tkinter is imported and can successfully create a window. |
110
- | `matplotlib_is_available_for_gui_plotting(termux_has_gui=False)` | Checks for Matplotlib and its TkAgg backend, required for interactive plotting. |
111
- | `matplotlib_is_available_for_headless_image_export()` | Checks for Matplotlib and its Agg backend, required for saving images without a GUI. |
112
- | `is_interactive_terminal()` | Checks if standard input and output streams are connected to a TTY (allows safe use of interactive prompts). |
147
+ ```python
148
+ open_text_file_in_default_app(filepath=Path('./config.json'))
149
+ ```
150
+ ---
113
151
 
114
152
  ## 🤝 Contributing
115
153
 
{pyhabitat-0.1.2 → pyhabitat-1.0.6}/README.md RENAMED
@@ -1,16 +1,30 @@
1
1
  # pyhabitat 🧭
2
2
 
3
- ## A Robust Environment and Build Introspection Library for Python
3
+ ## An Introspection Library for Python Environments and Builds
4
4
 
5
- **`pyhabitat`** is a focused, lightweight library designed to accurately and securely determine the execution context of a running Python script. It provides definitive checks for the Operating System (OS), common container/emulation environments (Termux, iSH), build states (PyInstaller, pipx), and the availability of GUI backends (Matplotlib, Tkinter).
5
+ **`pyhabitat`** is a **lightweight library for Python build and environment introspection**. It accurately and securely determines the execution context of a running script by providing definitive checks for:
6
6
 
7
- Stop writing verbose `sys.platform` and environment variable checks. Instead, use **`pyhabitat`** to implement architectural logic in your code.
7
+ * **OS and Environments:** Operating Systems and common container/emulation environments (e.g., Termux, iSH).
8
+ * **Build States:** Application build systems (e.g., PyInstaller, pipx).
9
+ * **GUI Backends:** Availability of graphical toolkits (e.g., Matplotlib, Tkinter).
10
+
11
+ Stop writing verbose `sys.platform` and environment variable checks. Use **`pyhabitat`** to implement clean, **architectural logic** based on the execution habitat.
12
+
13
+ This library is especially useful for **leveraging Python in mobile environments** (`Termux` on Android and `iSH` on iOS), which often have particular limitations and require special handling. For example, it helps automate work-arounds like using **localhost plotting** when `matplotlib` is unavailable or **web-based interfaces** when `tkinter` is missing.
14
+
15
+ Our team is fundamentally driven by enabling mobile computing for true utility applications, leveraging environments like Termux (Android) and iSH (iOS). This includes highly practical solutions, such as deploying a lightweight Python web server (e.g., Flask, http.server, FastAPI) directly on a handset, or orchestrating full-stack, utility-grade applications that allow technicians to manage data and systems right from their mobile device in a way that is cross-platform and not overly catered to the App Store.
16
+
17
+ Another key goal of this project is to facilitate the orchestration of wider system installation for **`pipx` CLI tools** for additional touch points, like addition to context menus and widgets.
18
+
19
+ Ultimately, [City-of-Memphis-Wastewater](https://github.com/City-of-Memphis-Wastewater) aims to produce **reference-quality code** for the documented proper approach. We recognize that many people (and bots) are searching for ideal solutions, and our functions are built upon extensive research and testing to go **beyond simple `platform.system()` checks**.
20
+
21
+ ---
8
22
 
9
23
  ## 🚀 Features
10
24
 
11
- * **Definitive Environment Checks:** Accurate detection for Windows, macOS (Apple), Linux, FreeBSD, Android (general), Termux, and iSH (iOS Alpine).
25
+ * **Definitive Environment Checks:** Rigorous checks catered to Termux and iSH (iOS Alpine). Accurate, typical modern detection for Windows, macOS (Apple), Linux, FreeBSD, Android.
12
26
  * **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).
13
- * **Build/Packaging Detection:** Reliable detection of standalone executables built by tools like PyInstaller, and, crucially, correct identification and exclusion of pipx-managed virtual environments.
27
+ * **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.
14
28
  * **Executable Type Inspection:** Uses file magic numbers (ELF and MZ) to confirm if the running script is a monolithic, frozen binary (non-pipx).
15
29
 
16
30
  ## 📦 Installation
@@ -18,6 +32,47 @@ Stop writing verbose `sys.platform` and environment variable checks. Instead, us
18
32
  ```bash
19
33
  pip install pyhabitat
20
34
  ```
35
+ ---
36
+
37
+ ## 📚 API Reference
38
+
39
+ ### OS and Environment
40
+
41
+ | Function | Description |
42
+ | :--- | :--- |
43
+ | `is_windows()` | Returns `True` on Windows. |
44
+ | `is_apple()` | Returns `True` on macOS (Darwin). |
45
+ | `is_linux()` | Returns `True` on Linux in general. |
46
+ | `is_termux()` | Returns `True` if running in the Termux Android environment. |
47
+ | `is_ish_alpine()` | Returns `True` if running in the iSH Alpine Linux iOS emulator. |
48
+ | `is_android()` | Returns `True` on any Android-based Linux environment. |
49
+
50
+ ### Build and Packaging
51
+
52
+ | Function | Description |
53
+ | :--- | :--- |
54
+ | `is_frozen()` | Returns `True` if the script is running as a standalone executable (any bundler). |
55
+ | `is_pipx()` | Returns `True` if running from a pipx managed virtual environment. |
56
+ | `is_elf()` | Checks if the executable is an ELF binary (Linux standalone executable), excluding pipx. |
57
+ | `is_windows_portable_executable()` | Checks if the executable is a Windows PE binary (MZ header), excluding pipx. |
58
+ | `is_macos_executable()` | Checks if the executable is a macOS/Darwin Mach-O binary, excluding pipx. |
59
+
60
+ ### Capabilities
61
+
62
+ | Function | Description |
63
+ | :--- | :--- |
64
+ | `tkinter_is_available()` | Checks if Tkinter is imported and can successfully create a window. |
65
+ | `matplotlib_is_available_for_gui_plotting(termux_has_gui=False)` | Checks for Matplotlib and its TkAgg backend, required for interactive plotting. |
66
+ | `matplotlib_is_available_for_headless_image_export()` | Checks for Matplotlib and its Agg backend, required for saving images without a GUI. |
67
+ | `is_interactive_terminal()` | Checks if standard input and output streams are connected to a TTY (allows safe use of interactive prompts). |
68
+ | `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). |
69
+
70
+ ### Actions
71
+ | Function | Description |
72
+ | :--- | :--- |
73
+ | `open_text_file_in_default_app()` | Smoothly opens a text file for editing (for configuration editing prompted by a CLI flag). |
74
+
75
+ ---
21
76
 
22
77
  ## 💻 Usage Examples
23
78
 
@@ -33,8 +88,13 @@ if is_pipx():
33
88
 
34
89
  elif is_frozen():
35
90
  print("Running as a frozen executable (PyInstaller, cx_Freeze, etc.).")
36
-
91
+
37
92
  elif is_termux():
93
+ # Expected cases:
94
+ #- pkg install python-numpy python-cryptography
95
+ #- Avoiding matplotlib unless the user explicitly confirms that termux_has_gui=False in matplotlib_is_available_for_gui_plotting(termux_has_gui=False).
96
+ #- Auto-selection of 'termux-open-url' and 'xdg-open' in logic.
97
+ #- Installation on the system, like orchestrating the construction of Termux Widget entries in ~/.shortcuts.
38
98
  print("Running in the Termux environment on Android.")
39
99
 
40
100
  elif is_windows():
@@ -64,36 +124,15 @@ else:
64
124
  print("Matplotlib is not installed or the environment is too restrictive for plotting.")
65
125
  ```
66
126
 
67
- ## 📚 API Reference
68
-
69
- ### OS and Environment
70
-
71
- | Function | Description |
72
- | :--- | :--- |
73
- | `is_windows()` | Returns `True` on Windows. |
74
- | `is_apple()` | Returns `True` on macOS (Darwin). |
75
- | `is_linux()` | Returns `True` on Linux in general. |
76
- | `is_termux()` | Returns `True` if running in the Termux Android environment. |
77
- | `is_ish_alpine()` | Returns `True` if running in the iSH Alpine Linux iOS emulator. |
78
- | `is_android()` | Returns `True` on any Android-based Linux environment. |
79
-
80
- ### Build and Packaging
81
-
82
- | Function | Description |
83
- | :--- | :--- |
84
- | `is_frozen()` | Returns `True` if the script is running as a standalone executable (any bundler). |
85
- | `is_pipx()` | Returns `True` if running from a pipx managed virtual environment. |
86
- | `is_elf()` | Checks if the executable is an ELF binary (Linux standalone executable), excluding pipx. |
87
- | `is_windows_portable_executable()` | Checks if the executable is a Windows PE binary (MZ header), excluding pipx. |
127
+ ### 3\. Text Editing
88
128
 
89
- ### Capabilities
129
+ Use this function to smoothly open a text file for editing.
130
+ Ideal use case: Edit a configuration file, if prompted by a CLI command like 'config --textedit'.
90
131
 
91
- | Function | Description |
92
- | :--- | :--- |
93
- | `tkinter_is_available()` | Checks if Tkinter is imported and can successfully create a window. |
94
- | `matplotlib_is_available_for_gui_plotting(termux_has_gui=False)` | Checks for Matplotlib and its TkAgg backend, required for interactive plotting. |
95
- | `matplotlib_is_available_for_headless_image_export()` | Checks for Matplotlib and its Agg backend, required for saving images without a GUI. |
96
- | `is_interactive_terminal()` | Checks if standard input and output streams are connected to a TTY (allows safe use of interactive prompts). |
132
+ ```python
133
+ open_text_file_in_default_app(filepath=Path('./config.json'))
134
+ ```
135
+ ---
97
136
 
98
137
  ## 🤝 Contributing
99
138
 
{pyhabitat-0.1.2 → pyhabitat-1.0.6}/pyhabitat.egg-info/PKG-INFO RENAMED
@@ -1,12 +1,11 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: pyhabitat
3
- Version: 0.1.2
4
- Summary: A robust library for detecting system environment, GUI, and build properties.
3
+ Version: 1.0.6
4
+ Summary: A lightweight library for detecting system environment, GUI, and build properties.
5
5
  Author-email: George Clayton Bennett <george.bennett@memphistn.gov>
6
- License: MIT
6
+ License-Expression: MIT
7
7
  Keywords: environment,os-detection,gui,build-system
8
8
  Classifier: Programming Language :: Python :: 3
9
- Classifier: License :: OSI Approved :: MIT License
10
9
  Classifier: Operating System :: OS Independent
11
10
  Classifier: Topic :: System :: Systems Administration
12
11
  Requires-Python: >=3.8
@@ -16,17 +15,31 @@ Dynamic: license-file
16
15
 
17
16
  # pyhabitat 🧭
18
17
 
19
- ## A Robust Environment and Build Introspection Library for Python
18
+ ## An Introspection Library for Python Environments and Builds
20
19
 
21
- **`pyhabitat`** is a focused, lightweight library designed to accurately and securely determine the execution context of a running Python script. It provides definitive checks for the Operating System (OS), common container/emulation environments (Termux, iSH), build states (PyInstaller, pipx), and the availability of GUI backends (Matplotlib, Tkinter).
20
+ **`pyhabitat`** is a **lightweight library for Python build and environment introspection**. It accurately and securely determines the execution context of a running script by providing definitive checks for:
22
21
 
23
- Stop writing verbose `sys.platform` and environment variable checks. Instead, use **`pyhabitat`** to implement architectural logic in your code.
22
+ * **OS and Environments:** Operating Systems and common container/emulation environments (e.g., Termux, iSH).
23
+ * **Build States:** Application build systems (e.g., PyInstaller, pipx).
24
+ * **GUI Backends:** Availability of graphical toolkits (e.g., Matplotlib, Tkinter).
25
+
26
+ Stop writing verbose `sys.platform` and environment variable checks. Use **`pyhabitat`** to implement clean, **architectural logic** based on the execution habitat.
27
+
28
+ This library is especially useful for **leveraging Python in mobile environments** (`Termux` on Android and `iSH` on iOS), which often have particular limitations and require special handling. For example, it helps automate work-arounds like using **localhost plotting** when `matplotlib` is unavailable or **web-based interfaces** when `tkinter` is missing.
29
+
30
+ Our team is fundamentally driven by enabling mobile computing for true utility applications, leveraging environments like Termux (Android) and iSH (iOS). This includes highly practical solutions, such as deploying a lightweight Python web server (e.g., Flask, http.server, FastAPI) directly on a handset, or orchestrating full-stack, utility-grade applications that allow technicians to manage data and systems right from their mobile device in a way that is cross-platform and not overly catered to the App Store.
31
+
32
+ Another key goal of this project is to facilitate the orchestration of wider system installation for **`pipx` CLI tools** for additional touch points, like addition to context menus and widgets.
33
+
34
+ Ultimately, [City-of-Memphis-Wastewater](https://github.com/City-of-Memphis-Wastewater) aims to produce **reference-quality code** for the documented proper approach. We recognize that many people (and bots) are searching for ideal solutions, and our functions are built upon extensive research and testing to go **beyond simple `platform.system()` checks**.
35
+
36
+ ---
24
37
 
25
38
  ## 🚀 Features
26
39
 
27
- * **Definitive Environment Checks:** Accurate detection for Windows, macOS (Apple), Linux, FreeBSD, Android (general), Termux, and iSH (iOS Alpine).
40
+ * **Definitive Environment Checks:** Rigorous checks catered to Termux and iSH (iOS Alpine). Accurate, typical modern detection for Windows, macOS (Apple), Linux, FreeBSD, Android.
28
41
  * **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).
29
- * **Build/Packaging Detection:** Reliable detection of standalone executables built by tools like PyInstaller, and, crucially, correct identification and exclusion of pipx-managed virtual environments.
42
+ * **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.
30
43
  * **Executable Type Inspection:** Uses file magic numbers (ELF and MZ) to confirm if the running script is a monolithic, frozen binary (non-pipx).
31
44
 
32
45
  ## 📦 Installation
@@ -34,6 +47,47 @@ Stop writing verbose `sys.platform` and environment variable checks. Instead, us
34
47
  ```bash
35
48
  pip install pyhabitat
36
49
  ```
50
+ ---
51
+
52
+ ## 📚 API Reference
53
+
54
+ ### OS and Environment
55
+
56
+ | Function | Description |
57
+ | :--- | :--- |
58
+ | `is_windows()` | Returns `True` on Windows. |
59
+ | `is_apple()` | Returns `True` on macOS (Darwin). |
60
+ | `is_linux()` | Returns `True` on Linux in general. |
61
+ | `is_termux()` | Returns `True` if running in the Termux Android environment. |
62
+ | `is_ish_alpine()` | Returns `True` if running in the iSH Alpine Linux iOS emulator. |
63
+ | `is_android()` | Returns `True` on any Android-based Linux environment. |
64
+
65
+ ### Build and Packaging
66
+
67
+ | Function | Description |
68
+ | :--- | :--- |
69
+ | `is_frozen()` | Returns `True` if the script is running as a standalone executable (any bundler). |
70
+ | `is_pipx()` | Returns `True` if running from a pipx managed virtual environment. |
71
+ | `is_elf()` | Checks if the executable is an ELF binary (Linux standalone executable), excluding pipx. |
72
+ | `is_windows_portable_executable()` | Checks if the executable is a Windows PE binary (MZ header), excluding pipx. |
73
+ | `is_macos_executable()` | Checks if the executable is a macOS/Darwin Mach-O binary, excluding pipx. |
74
+
75
+ ### Capabilities
76
+
77
+ | Function | Description |
78
+ | :--- | :--- |
79
+ | `tkinter_is_available()` | Checks if Tkinter is imported and can successfully create a window. |
80
+ | `matplotlib_is_available_for_gui_plotting(termux_has_gui=False)` | Checks for Matplotlib and its TkAgg backend, required for interactive plotting. |
81
+ | `matplotlib_is_available_for_headless_image_export()` | Checks for Matplotlib and its Agg backend, required for saving images without a GUI. |
82
+ | `is_interactive_terminal()` | Checks if standard input and output streams are connected to a TTY (allows safe use of interactive prompts). |
83
+ | `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). |
84
+
85
+ ### Actions
86
+ | Function | Description |
87
+ | :--- | :--- |
88
+ | `open_text_file_in_default_app()` | Smoothly opens a text file for editing (for configuration editing prompted by a CLI flag). |
89
+
90
+ ---
37
91
 
38
92
  ## 💻 Usage Examples
39
93
 
@@ -49,8 +103,13 @@ if is_pipx():
49
103
 
50
104
  elif is_frozen():
51
105
  print("Running as a frozen executable (PyInstaller, cx_Freeze, etc.).")
52
-
106
+
53
107
  elif is_termux():
108
+ # Expected cases:
109
+ #- pkg install python-numpy python-cryptography
110
+ #- Avoiding matplotlib unless the user explicitly confirms that termux_has_gui=False in matplotlib_is_available_for_gui_plotting(termux_has_gui=False).
111
+ #- Auto-selection of 'termux-open-url' and 'xdg-open' in logic.
112
+ #- Installation on the system, like orchestrating the construction of Termux Widget entries in ~/.shortcuts.
54
113
  print("Running in the Termux environment on Android.")
55
114
 
56
115
  elif is_windows():
@@ -80,36 +139,15 @@ else:
80
139
  print("Matplotlib is not installed or the environment is too restrictive for plotting.")
81
140
  ```
82
141
 
83
- ## 📚 API Reference
84
-
85
- ### OS and Environment
86
-
87
- | Function | Description |
88
- | :--- | :--- |
89
- | `is_windows()` | Returns `True` on Windows. |
90
- | `is_apple()` | Returns `True` on macOS (Darwin). |
91
- | `is_linux()` | Returns `True` on Linux in general. |
92
- | `is_termux()` | Returns `True` if running in the Termux Android environment. |
93
- | `is_ish_alpine()` | Returns `True` if running in the iSH Alpine Linux iOS emulator. |
94
- | `is_android()` | Returns `True` on any Android-based Linux environment. |
95
-
96
- ### Build and Packaging
97
-
98
- | Function | Description |
99
- | :--- | :--- |
100
- | `is_frozen()` | Returns `True` if the script is running as a standalone executable (any bundler). |
101
- | `is_pipx()` | Returns `True` if running from a pipx managed virtual environment. |
102
- | `is_elf()` | Checks if the executable is an ELF binary (Linux standalone executable), excluding pipx. |
103
- | `is_windows_portable_executable()` | Checks if the executable is a Windows PE binary (MZ header), excluding pipx. |
142
+ ### 3\. Text Editing
104
143
 
105
- ### Capabilities
144
+ Use this function to smoothly open a text file for editing.
145
+ Ideal use case: Edit a configuration file, if prompted by a CLI command like 'config --textedit'.
106
146
 
107
- | Function | Description |
108
- | :--- | :--- |
109
- | `tkinter_is_available()` | Checks if Tkinter is imported and can successfully create a window. |
110
- | `matplotlib_is_available_for_gui_plotting(termux_has_gui=False)` | Checks for Matplotlib and its TkAgg backend, required for interactive plotting. |
111
- | `matplotlib_is_available_for_headless_image_export()` | Checks for Matplotlib and its Agg backend, required for saving images without a GUI. |
112
- | `is_interactive_terminal()` | Checks if standard input and output streams are connected to a TTY (allows safe use of interactive prompts). |
147
+ ```python
148
+ open_text_file_in_default_app(filepath=Path('./config.json'))
149
+ ```
150
+ ---
113
151
 
114
152
  ## 🤝 Contributing
115
153
 
{pyhabitat-0.1.2 → pyhabitat-1.0.6}/pyproject.toml RENAMED
@@ -6,22 +6,26 @@ build-backend = "setuptools.build_meta"
6
6
 
7
7
  [project]
8
8
  name = "pyhabitat"
9
- version = "0.1.2"
9
+ version = "1.0.6"
10
+ #dynamic = ["version"] #
10
11
  authors = [
11
12
  { name="George Clayton Bennett", email="george.bennett@memphistn.gov" },
12
13
  ]
13
- description = "A robust library for detecting system environment, GUI, and build properties."
14
+ description = "A lightweight library for detecting system environment, GUI, and build properties."
14
15
  readme = "README.md"
15
16
  requires-python = ">=3.8"
16
- license = { text = "MIT" }
17
+ license = "MIT"
17
18
  keywords = ["environment", "os-detection", "gui", "build-system"]
18
19
  classifiers = [
19
20
  "Programming Language :: Python :: 3",
20
- "License :: OSI Approved :: MIT License",
21
21
  "Operating System :: OS Independent",
22
22
  "Topic :: System :: Systems Administration",
23
23
  ]
24
24
 
25
25
  [tool.setuptools.packages.find]
26
26
  where = ["."]
27
- include = ["pyhabitat"] # Only include the main package
27
+ include = ["pyhabitat"] # Only include the main package
28
+
29
+ [tool.setuptools_scm]
30
+ # This tells setuptools_scm to look at your git history/tags for the version
31
+ write_to = "pyhabitat/_version.py"
{pyhabitat-0.1.2 → pyhabitat-1.0.6}/LICENSE RENAMED
File without changes
{pyhabitat-0.1.2 → pyhabitat-1.0.6}/setup.cfg RENAMED
File without changes