nano-dev-utils 1.6.2__tar.gz → 1.7.0__tar.gz

{nano_dev_utils-1.6.2 → nano_dev_utils-1.7.0}/.gitignore

@@ -174,4 +174,6 @@ cython_debug/
 .pypirc
 
 /src/*/debug.py
-/src/*/*.log
+/src/*/*.log
+
+update_package.py

{nano_dev_utils-1.6.2 → nano_dev_utils-1.7.0}/.idea/workspace.xml

@@ -4,9 +4,16 @@
     <option name="autoReloadType" value="SELECTIVE" />
   </component>
   <component name="ChangeListManager">
-    <list default="true" id="1859e23b-7665-4b92-98cc-65e07a208923" name="Changes" comment="versioning updates;&#10;load_cfg_file minor update;&#10;v1.6.1">
-      <change beforePath="$PROJECT_DIR$/src/nano_dev_utils/__main__.py" beforeDir="false" afterPath="$PROJECT_DIR$/src/nano_dev_utils/__main__.py" afterDir="false" />
+    <list default="true" id="1859e23b-7665-4b92-98cc-65e07a208923" name="Changes" comment="minor bugfix (cfg); &#10;Bumped minor version&#10;v1.6.2">
+      <change beforePath="$PROJECT_DIR$/.gitignore" beforeDir="false" afterPath="$PROJECT_DIR$/.gitignore" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/README.md" beforeDir="false" afterPath="$PROJECT_DIR$/README.md" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/pyproject.toml" beforeDir="false" afterPath="$PROJECT_DIR$/pyproject.toml" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/src/nano_dev_utils/__init__.py" beforeDir="false" afterPath="$PROJECT_DIR$/src/nano_dev_utils/__init__.py" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/src/nano_dev_utils/__main__.py" beforeDir="false" />
       <change beforePath="$PROJECT_DIR$/src/nano_dev_utils/__version__.py" beforeDir="false" afterPath="$PROJECT_DIR$/src/nano_dev_utils/__version__.py" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/src/nano_dev_utils/_constants.py" beforeDir="false" afterPath="$PROJECT_DIR$/src/nano_dev_utils/_constants.py" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/src/nano_dev_utils/file_tree_display.py" beforeDir="false" />
+      <change beforePath="$PROJECT_DIR$/tests/test_file_tree_display.py" beforeDir="false" />
     </list>
     <option name="SHOW_DIALOG" value="false" />
     <option name="HIGHLIGHT_CONFLICTS" value="true" />
@@ -24,7 +31,7 @@
     <option name="PUSH_AUTO_UPDATE" value="true" />
     <option name="RECENT_BRANCH_BY_REPOSITORY">
       <map>
-        <entry key="$PROJECT_DIR$" value="FI-CLI" />
+        <entry key="$PROJECT_DIR$" value="master" />
       </map>
     </option>
     <option name="RECENT_GIT_ROOT_PATH" value="$PROJECT_DIR$" />
@@ -59,7 +66,7 @@
     &quot;Python.test_timer.executor&quot;: &quot;Run&quot;,
     &quot;Python.update_package.executor&quot;: &quot;Run&quot;,
     &quot;RunOnceActivity.ShowReadmeOnStart&quot;: &quot;true&quot;,
-    &quot;git-widget-placeholder&quot;: &quot;master&quot;,
+    &quot;git-widget-placeholder&quot;: &quot;FI-CLI&quot;,
     &quot;ignore.virus.scanning.warn.message&quot;: &quot;true&quot;,
     &quot;last_opened_file_path&quot;: &quot;C:/GitHubWS/nano_dev_utils/src&quot;,
     &quot;settings.editor.selected.configurable&quot;: &quot;com.jetbrains.python.configuration.PyActiveSdkModuleConfigurable&quot;,
@@ -81,7 +88,7 @@
       <recent name="C:\GitHubWS\nano_dev_utils\tests" />
     </key>
   </component>
-  <component name="RunManager" selected="Python.benchtest_bkp">
+  <component name="RunManager" selected="Python tests.Python tests in tests">
     <configuration name="benchtest_bkp" type="PythonConfigurationType" factoryName="Python" temporary="true" nameIsGenerated="true">
       <module name="nano_dev_utils" />
       <option name="ENV_FILES" value="" />
@@ -126,21 +133,6 @@
       <option name="INPUT_FILE" value="" />
       <method v="2" />
     </configuration>
-    <configuration name="Python tests in test_file_tree_display.py" type="tests" factoryName="Autodetect" temporary="true" nameIsGenerated="true">
-      <module name="nano_dev_utils" />
-      <option name="ENV_FILES" value="" />
-      <option name="INTERPRETER_OPTIONS" value="" />
-      <option name="PARENT_ENVS" value="true" />
-      <option name="SDK_HOME" value="" />
-      <option name="WORKING_DIRECTORY" value="$PROJECT_DIR$/tests" />
-      <option name="IS_MODULE_SDK" value="true" />
-      <option name="ADD_CONTENT_ROOTS" value="true" />
-      <option name="ADD_SOURCE_ROOTS" value="true" />
-      <option name="_new_additionalArguments" value="&quot;&quot;" />
-      <option name="_new_target" value="&quot;$PROJECT_DIR$/tests/test_file_tree_display.py&quot;" />
-      <option name="_new_targetType" value="&quot;PATH&quot;" />
-      <method v="2" />
-    </configuration>
     <configuration name="Python tests in tests" type="tests" factoryName="Autodetect" temporary="true" nameIsGenerated="true">
       <module name="nano_dev_utils" />
       <option name="ENV_FILES" value="" />
@@ -159,15 +151,13 @@
     <list>
       <item itemvalue="Python.update_package" />
       <item itemvalue="Python.benchtest_bkp" />
-      <item itemvalue="Python tests.Python tests in test_file_tree_display.py" />
       <item itemvalue="Python tests.Python tests in tests" />
     </list>
     <recent_temporary>
       <list>
-        <item itemvalue="Python.update_package" />
         <item itemvalue="Python tests.Python tests in tests" />
+        <item itemvalue="Python.update_package" />
         <item itemvalue="Python.benchtest_bkp" />
-        <item itemvalue="Python tests.Python tests in test_file_tree_display.py" />
       </list>
     </recent_temporary>
   </component>
@@ -187,14 +177,6 @@
       <option name="presentableId" value="Default" />
       <updated>1746126505743</updated>
     </task>
-    <task id="LOCAL-00098" summary="Readme updates">
-      <option name="closed" value="true" />
-      <created>1762078800875</created>
-      <option name="number" value="00098" />
-      <option name="presentableId" value="LOCAL-00098" />
-      <option name="project" value="LOCAL" />
-      <updated>1762078800875</updated>
-    </task>
     <task id="LOCAL-00099" summary="+res_formatter, a wrapper for the private static _duration_formatter.">
       <option name="closed" value="true" />
       <created>1762081915651</created>
@@ -579,7 +561,15 @@
       <option name="project" value="LOCAL" />
       <updated>1762712425856</updated>
     </task>
-    <option name="localTasksCounter" value="147" />
+    <task id="LOCAL-00147" summary="minor bugfix (cfg); &#10;Bumped minor version&#10;v1.6.2">
+      <option name="closed" value="true" />
+      <created>1762716808091</created>
+      <option name="number" value="00147" />
+      <option name="presentableId" value="LOCAL-00147" />
+      <option name="project" value="LOCAL" />
+      <updated>1762716808091</updated>
+    </task>
+    <option name="localTasksCounter" value="148" />
     <servers />
   </component>
   <component name="Vcs.Log.Tabs.Properties">
@@ -636,7 +626,6 @@
     </option>
   </component>
   <component name="VcsManagerConfiguration">
-    <MESSAGE value="upgrading connector style (WIP)" />
     <MESSAGE value="optimizing performance:&#10;-reduced alloc &amp; overhead;&#10;-precomputed style dict and sorting outside the recursive _build_tree;&#10;-improved string ops:&#10;used StringIO for better memory efficiency&#10;-improved traversal&#10;&#10;Unit tests updates" />
     <MESSAGE value="-removing single char old style fallback &#10;+ unit test for custom styles dynamically added by user" />
     <MESSAGE value="README updates related to FTD" />
@@ -661,6 +650,7 @@
     <MESSAGE value="+ftd cli version" />
     <MESSAGE value="pyproject.toml: &#10;dynamic version; &#10;ftd cli shortcut;&#10;hatch.version path according to __version__ &#10;v1.6.0" />
     <MESSAGE value="versioning updates;&#10;load_cfg_file minor update;&#10;v1.6.1" />
-    <option name="LAST_COMMIT_MESSAGE" value="versioning updates;&#10;load_cfg_file minor update;&#10;v1.6.1" />
+    <MESSAGE value="minor bugfix (cfg); &#10;Bumped minor version&#10;v1.6.2" />
+    <option name="LAST_COMMIT_MESSAGE" value="minor bugfix (cfg); &#10;Bumped minor version&#10;v1.6.2" />
   </component>
 </project>

nano_dev_utils-1.7.0/PKG-INFO

@@ -0,0 +1,180 @@
+Metadata-Version: 2.4
+Name: nano_dev_utils
+Version: 1.7.0
+Summary: A collection of small Python utilities for developers.
+Project-URL: Homepage, https://github.com/yaronday/nano_utils
+Project-URL: Issues, https://github.com/yaronday/nano_utils/issues
+Project-URL: license, https://github.com/yaronday/nano_dev_utils/blob/master/LICENSE
+Author-email: Yaron Dayan <yaronday77@gmail.com>
+License: MIT
+License-File: LICENSE
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Requires-Dist: build>=1.3.0
+Description-Content-Type: text/markdown
+
+# nano_dev_utils
+
+A collection of small Python utilities for developers.
+[PYPI package: nano-dev-utils](https://pypi.org/project/nano-dev-utils)
+
+## Modules
+
+### `timers.py`
+
+This module provides a `Timer` class for measuring the execution time of code blocks and functions with additional features like timeout control and multi-iteration averaging.
+
+#### `Timer` Class
+
+* **`__init__(self, precision: int = 4, verbose: bool = False, printout: bool = False)`**: Initializes a `Timer` instance.
+    * `precision`: The number of decimal places to record and display time durations. Defaults to 4.
+    * `verbose`: Optionally displays the function's positional arguments (args) and keyword arguments (kwargs). Defaults to `False`.
+    * `printout`: Allows printing to console.
+
+* **`def timeit(
+        self,
+        iterations: int = 1,
+        timeout: float | None = None,
+        per_iteration: bool = False,
+    ) -> Callable[[Callable[P, Any]], Callable[P, Any]]:`**:   
+      Decorator that times either **sync** or **async** function execution with advanced features:
+    * `iterations`: Number of times to run the function (for averaging). Defaults to 1.
+    * `timeout`: Maximum allowed execution time in seconds. When exceeded:
+        * Raises `TimeoutError` immediately
+        * **Warning:** The function execution will be aborted mid-operation
+        * No return value will be available if timeout occurs
+    * `per_iteration`: If True, applies timeout check to each iteration; otherwise checks total time across all iterations.
+    * Features:
+        * Records execution times
+        * Handles timeout conditions
+        * Calculates average execution time across iterations
+        * Logs the function name and execution time (with optional arguments)
+        * Returns the result of the original function (unless timeout occurs)
+
+#### Example Usage:
+
+```python
+import time
+import logging
+from nano_dev_utils import timer
+
+# if printout is not enabled, a logger must be configured in order to see timing results
+logging.basicConfig(filename='timer example.log',
+                    level=logging.INFO,  # DEBUG, WARNING, ERROR, CRITICAL
+                    format='%(asctime)s - %(levelname)s: %(message)s',
+                    datefmt='%d-%m-%Y %H:%M:%S')
+
+# Basic timing
+@timer.timeit()
+def my_function(a, b=10):
+    """A sample function."""
+    time.sleep(0.1)
+    return a + b
+
+timer.init(precision=6, verbose=True)
+'''Alternative options: 
+timer.update({'precision': 6, 'verbose': True})  # 1. Using update method  
+
+from nano_dev_utils.timers import Timer  # 2. explicit instantiation
+timer = Timer(precision=6, verbose=True)  
+'''
+
+timer.update({'printout': True})  # allow printing to console
+
+# Advanced usage with timeout and iterations
+@timer.timeit(iterations=5, timeout=0.5, per_iteration=True)
+def critical_function(x):
+    """Function with timeout check per iteration."""
+    time.sleep(0.08)
+    return x * 2
+
+result1 = my_function(5, b=20)  # Shows args/kwargs and timing
+result2 = critical_function(10)  # Runs 5 times with per-iteration timeout
+```
+
+### `dynamic_importer.py`
+
+This module provides an `Importer` class for lazy loading and caching module imports.
+
+#### `Importer` Class
+
+* **`__init__(self)`**: Initializes an `Importer` instance with an empty dictionary `imported_modules` to cache imported modules.
+
+* **`import_mod_from_lib(self, library: str, module_name: str) -> ModuleType | Any`**: Lazily imports a module from a specified library and caches it.
+    * `library` (str): The name of the library (e.g., "os", "requests").
+    * `module_name` (str): The name of the module to import within the library (e.g., "path", "get").
+    * Returns the imported module. If the module has already been imported, it returns a cached instance.
+    * Raises `ImportError` if the module cannot be found.
+
+#### Example Usage:
+
+```python
+from nano_dev_utils import importer
+
+os_path = importer.import_mod_from_lib("os", "path")
+print(f"Imported os.path: {os_path}")
+
+requests_get = importer.import_mod_from_lib("requests", "get")
+print(f"Imported requests.get: {requests_get}")
+
+# Subsequent calls will return the cached module
+os_path_again = importer.import_mod_from_lib("os", "path")
+print(f"Imported os.path again (cached): {os_path_again}")
+```
+
+### `release_ports.py`
+
+This module provides a `PortsRelease` class to identify and release processes 
+listening on specified TCP ports.    
+It supports Windows, Linux, and macOS.
+
+#### `PortsRelease` Class
+
+* **`__init__(self, default_ports: list[int] | None = None)`**: 
+* Initializes a `PortsRelease` instance.
+    * `default_ports`: A list of default ports to manage. If not provided, it defaults to `[6277, 6274]`.
+
+* **`get_pid_by_port(self, port: int) -> int | None`**: A static method that attempts to find   
+     a process ID (PID) listening on a given `port`.       
+*    It uses platform-specific commands (`netstat`, `ss`, `lsof`).       
+*    Returns the PID if found, otherwise `None`.    
+
+* **`kill_process(self, pid: int) -> bool`**: A static method that attempts to kill the process 
+  with the given `pid`.   
+* It uses platform-specific commands (`taskkill`, `kill -9`). 
+* Returns `True` if the process was successfully killed, `False` otherwise. 
+
+* **`release_all(self, ports: list[int] | None = None) -> None`**: Releases all processes listening on the specified `ports`.   
+    * `ports`: A list of ports to release.   
+    * If `None`, it uses the `default_ports` defined during initialization.   
+    * For each port, it first tries to get the PID and then attempts to kill the process.       
+    * It logs the actions and any errors encountered. Invalid port numbers in the provided list are skipped.
+
+#### Example Usage:
+
+```python
+import logging
+from nano_dev_utils import ports_release, PortsRelease
+
+ 
+logging.basicConfig(filename='port release.log',
+                    level=logging.INFO,  # DEBUG, WARNING, ERROR, CRITICAL 
+                    format='%(asctime)s - %(levelname)s: %(message)s',
+                    datefmt='%d-%m-%Y %H:%M:%S')
+
+
+ports_release.release_all()
+
+# Create an instance with custom ports
+custom_ports_releaser = PortsRelease(default_ports=[8080, 9000, 6274])
+custom_ports_releaser.release_all(ports=[8080, 9000])
+
+# Release only the default ports
+ports_release.release_all()
+```
+
+
+## License
+This project is licensed under the MIT License. 
+See [LICENSE](https://github.com/yaronday/nano_dev_utils/blob/master/LICENSE) for details.

nano_dev_utils-1.7.0/README.md

@@ -0,0 +1,164 @@
+# nano_dev_utils
+
+A collection of small Python utilities for developers.
+[PYPI package: nano-dev-utils](https://pypi.org/project/nano-dev-utils)
+
+## Modules
+
+### `timers.py`
+
+This module provides a `Timer` class for measuring the execution time of code blocks and functions with additional features like timeout control and multi-iteration averaging.
+
+#### `Timer` Class
+
+* **`__init__(self, precision: int = 4, verbose: bool = False, printout: bool = False)`**: Initializes a `Timer` instance.
+    * `precision`: The number of decimal places to record and display time durations. Defaults to 4.
+    * `verbose`: Optionally displays the function's positional arguments (args) and keyword arguments (kwargs). Defaults to `False`.
+    * `printout`: Allows printing to console.
+
+* **`def timeit(
+        self,
+        iterations: int = 1,
+        timeout: float | None = None,
+        per_iteration: bool = False,
+    ) -> Callable[[Callable[P, Any]], Callable[P, Any]]:`**:   
+      Decorator that times either **sync** or **async** function execution with advanced features:
+    * `iterations`: Number of times to run the function (for averaging). Defaults to 1.
+    * `timeout`: Maximum allowed execution time in seconds. When exceeded:
+        * Raises `TimeoutError` immediately
+        * **Warning:** The function execution will be aborted mid-operation
+        * No return value will be available if timeout occurs
+    * `per_iteration`: If True, applies timeout check to each iteration; otherwise checks total time across all iterations.
+    * Features:
+        * Records execution times
+        * Handles timeout conditions
+        * Calculates average execution time across iterations
+        * Logs the function name and execution time (with optional arguments)
+        * Returns the result of the original function (unless timeout occurs)
+
+#### Example Usage:
+
+```python
+import time
+import logging
+from nano_dev_utils import timer
+
+# if printout is not enabled, a logger must be configured in order to see timing results
+logging.basicConfig(filename='timer example.log',
+                    level=logging.INFO,  # DEBUG, WARNING, ERROR, CRITICAL
+                    format='%(asctime)s - %(levelname)s: %(message)s',
+                    datefmt='%d-%m-%Y %H:%M:%S')
+
+# Basic timing
+@timer.timeit()
+def my_function(a, b=10):
+    """A sample function."""
+    time.sleep(0.1)
+    return a + b
+
+timer.init(precision=6, verbose=True)
+'''Alternative options: 
+timer.update({'precision': 6, 'verbose': True})  # 1. Using update method  
+
+from nano_dev_utils.timers import Timer  # 2. explicit instantiation
+timer = Timer(precision=6, verbose=True)  
+'''
+
+timer.update({'printout': True})  # allow printing to console
+
+# Advanced usage with timeout and iterations
+@timer.timeit(iterations=5, timeout=0.5, per_iteration=True)
+def critical_function(x):
+    """Function with timeout check per iteration."""
+    time.sleep(0.08)
+    return x * 2
+
+result1 = my_function(5, b=20)  # Shows args/kwargs and timing
+result2 = critical_function(10)  # Runs 5 times with per-iteration timeout
+```
+
+### `dynamic_importer.py`
+
+This module provides an `Importer` class for lazy loading and caching module imports.
+
+#### `Importer` Class
+
+* **`__init__(self)`**: Initializes an `Importer` instance with an empty dictionary `imported_modules` to cache imported modules.
+
+* **`import_mod_from_lib(self, library: str, module_name: str) -> ModuleType | Any`**: Lazily imports a module from a specified library and caches it.
+    * `library` (str): The name of the library (e.g., "os", "requests").
+    * `module_name` (str): The name of the module to import within the library (e.g., "path", "get").
+    * Returns the imported module. If the module has already been imported, it returns a cached instance.
+    * Raises `ImportError` if the module cannot be found.
+
+#### Example Usage:
+
+```python
+from nano_dev_utils import importer
+
+os_path = importer.import_mod_from_lib("os", "path")
+print(f"Imported os.path: {os_path}")
+
+requests_get = importer.import_mod_from_lib("requests", "get")
+print(f"Imported requests.get: {requests_get}")
+
+# Subsequent calls will return the cached module
+os_path_again = importer.import_mod_from_lib("os", "path")
+print(f"Imported os.path again (cached): {os_path_again}")
+```
+
+### `release_ports.py`
+
+This module provides a `PortsRelease` class to identify and release processes 
+listening on specified TCP ports.    
+It supports Windows, Linux, and macOS.
+
+#### `PortsRelease` Class
+
+* **`__init__(self, default_ports: list[int] | None = None)`**: 
+* Initializes a `PortsRelease` instance.
+    * `default_ports`: A list of default ports to manage. If not provided, it defaults to `[6277, 6274]`.
+
+* **`get_pid_by_port(self, port: int) -> int | None`**: A static method that attempts to find   
+     a process ID (PID) listening on a given `port`.       
+*    It uses platform-specific commands (`netstat`, `ss`, `lsof`).       
+*    Returns the PID if found, otherwise `None`.    
+
+* **`kill_process(self, pid: int) -> bool`**: A static method that attempts to kill the process 
+  with the given `pid`.   
+* It uses platform-specific commands (`taskkill`, `kill -9`). 
+* Returns `True` if the process was successfully killed, `False` otherwise. 
+
+* **`release_all(self, ports: list[int] | None = None) -> None`**: Releases all processes listening on the specified `ports`.   
+    * `ports`: A list of ports to release.   
+    * If `None`, it uses the `default_ports` defined during initialization.   
+    * For each port, it first tries to get the PID and then attempts to kill the process.       
+    * It logs the actions and any errors encountered. Invalid port numbers in the provided list are skipped.
+
+#### Example Usage:
+
+```python
+import logging
+from nano_dev_utils import ports_release, PortsRelease
+
+ 
+logging.basicConfig(filename='port release.log',
+                    level=logging.INFO,  # DEBUG, WARNING, ERROR, CRITICAL 
+                    format='%(asctime)s - %(levelname)s: %(message)s',
+                    datefmt='%d-%m-%Y %H:%M:%S')
+
+
+ports_release.release_all()
+
+# Create an instance with custom ports
+custom_ports_releaser = PortsRelease(default_ports=[8080, 9000, 6274])
+custom_ports_releaser.release_all(ports=[8080, 9000])
+
+# Release only the default ports
+ports_release.release_all()
+```
+
+
+## License
+This project is licensed under the MIT License. 
+See [LICENSE](https://github.com/yaronday/nano_dev_utils/blob/master/LICENSE) for details.

{nano_dev_utils-1.6.2 → nano_dev_utils-1.7.0}/pyproject.toml

@@ -21,9 +21,6 @@ Homepage = "https://github.com/yaronday/nano_utils"
 Issues = "https://github.com/yaronday/nano_utils/issues"
 license = "https://github.com/yaronday/nano_dev_utils/blob/master/LICENSE"
 
-[project.scripts]
-ftd = "nano_dev_utils.__main__:main"
-
 [project.files]
 license = { path = "LICENSE" }
 

{nano_dev_utils-1.6.2 → nano_dev_utils-1.7.0}/src/nano_dev_utils/__init__.py

@@ -2,7 +2,6 @@
 Copyright (c) 2025 Yaron Dayan
 """
 
-from pathlib import Path
 from importlib.metadata import version
 from .dynamic_importer import Importer
 from .timers import Timer
@@ -15,14 +14,12 @@ from .common import (
     FilterSet,
     load_cfg_file,
 )
-from .file_tree_display import FileTreeDisplay
 
 from ._constants import PKG_NAME
 
 timer = Timer()
 ports_release = PortsRelease()
 importer = Importer()
-filetree_display = FileTreeDisplay(root_dir=str(Path.cwd()))
 predicate_builder = PredicateBuilder
 
 __version__ = version(PKG_NAME)
@@ -42,7 +39,5 @@ __all__ = [
     'timer',
     'ports_release',
     'importer',
-    'filetree_display',
-    'FileTreeDisplay',
     'load_cfg_file',
 ]

nano_dev_utils-1.7.0/src/nano_dev_utils/__version__.py

@@ -0,0 +1 @@
+__version__ = '1.7.0'

nano_dev_utils-1.7.0/src/nano_dev_utils/_constants.py

@@ -0,0 +1 @@
+PKG_NAME = 'nano-dev-utils'