nano-dev-utils 0.3.4__tar.gz → 0.4.1__tar.gz

{nano_dev_utils-0.3.4 → nano_dev_utils-0.4.1}/.idea/workspace.xml

@@ -4,7 +4,11 @@
     <option name="autoReloadType" value="SELECTIVE" />
   </component>
   <component name="ChangeListManager">
-    <list default="true" id="96bbbefe-efb6-42c4-93da-e069ac3e654f" name="Changes" comment="minor update" />
+    <list default="true" id="96bbbefe-efb6-42c4-93da-e069ac3e654f" name="Changes" comment="release_ports: Externalizing logger's config to a user's app. &#10;timers: improve code, docstring and type hinting&#10;README updates IAW with the above changes &#10;Version update: 0.4.0">
+      <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$/tests/testing_release_ports.py" beforeDir="false" afterPath="$PROJECT_DIR$/tests/testing_release_ports.py" afterDir="false" />
+    </list>
     <option name="SHOW_DIALOG" value="false" />
     <option name="HIGHLIGHT_CONFLICTS" value="true" />
     <option name="HIGHLIGHT_NON_ACTIVE_CHANGELIST" value="false" />
@@ -27,18 +31,18 @@
     <option name="showLibraryContents" value="true" />
     <option name="showMembers" value="true" />
   </component>
-  <component name="PropertiesComponent"><![CDATA[{
-  "keyToString": {
-    "Python tests.Python tests in testing_release_ports.py.executor": "Run",
-    "Python tests.Python tests in testing_timer.py.executor": "Run",
-    "Python tests.Python tests in tests.executor": "Run",
-    "RunOnceActivity.ShowReadmeOnStart": "true",
-    "git-widget-placeholder": "master",
-    "ignore.virus.scanning.warn.message": "true",
-    "last_opened_file_path": "C:/GitHubWS/nano_dev_utils",
-    "settings.editor.selected.configurable": "com.jetbrains.python.configuration.PyActiveSdkModuleConfigurable"
+  <component name="PropertiesComponent">{
+  &quot;keyToString&quot;: {
+    &quot;Python tests.Python tests in testing_release_ports.py.executor&quot;: &quot;Run&quot;,
+    &quot;Python tests.Python tests in testing_timer.py.executor&quot;: &quot;Run&quot;,
+    &quot;Python tests.Python tests in tests.executor&quot;: &quot;Run&quot;,
+    &quot;RunOnceActivity.ShowReadmeOnStart&quot;: &quot;true&quot;,
+    &quot;git-widget-placeholder&quot;: &quot;master&quot;,
+    &quot;ignore.virus.scanning.warn.message&quot;: &quot;true&quot;,
+    &quot;last_opened_file_path&quot;: &quot;C:/GitHubWS/nano_dev_utils&quot;,
+    &quot;settings.editor.selected.configurable&quot;: &quot;com.jetbrains.python.configuration.PyActiveSdkModuleConfigurable&quot;
   }
-}]]></component>
+}</component>
   <component name="RunManager" selected="Python tests.Python tests in tests">
     <configuration name="Python tests in testing_release_ports.py" type="tests" factoryName="Autodetect" temporary="true" nameIsGenerated="true">
       <module name="nano_dev_utils" />
@@ -88,8 +92,8 @@
     <recent_temporary>
       <list>
         <item itemvalue="Python tests.Python tests in tests" />
-        <item itemvalue="Python tests.Python tests in testing_timer.py" />
         <item itemvalue="Python tests.Python tests in testing_release_ports.py" />
+        <item itemvalue="Python tests.Python tests in testing_timer.py" />
         <item itemvalue="Python tests.Python tests in testing_release_ports.py" />
       </list>
     </recent_temporary>
@@ -238,7 +242,31 @@
       <option name="project" value="LOCAL" />
       <updated>1745715934159</updated>
     </task>
-    <option name="localTasksCounter" value="17" />
+    <task id="LOCAL-00017" summary="readme typo fixes">
+      <option name="closed" value="true" />
+      <created>1745716694896</created>
+      <option name="number" value="00017" />
+      <option name="presentableId" value="LOCAL-00017" />
+      <option name="project" value="LOCAL" />
+      <updated>1745716694896</updated>
+    </task>
+    <task id="LOCAL-00018" summary="minor update">
+      <option name="closed" value="true" />
+      <created>1745716727869</created>
+      <option name="number" value="00018" />
+      <option name="presentableId" value="LOCAL-00018" />
+      <option name="project" value="LOCAL" />
+      <updated>1745716727869</updated>
+    </task>
+    <task id="LOCAL-00019" summary="release_ports: Externalizing logger's config to a user's app. &#10;timers: improve code, docstring and type hinting&#10;README updates IAW with the above changes &#10;Version update: 0.4.0">
+      <option name="closed" value="true" />
+      <created>1745763645981</created>
+      <option name="number" value="00019" />
+      <option name="presentableId" value="LOCAL-00019" />
+      <option name="project" value="LOCAL" />
+      <updated>1745763645981</updated>
+    </task>
+    <option name="localTasksCounter" value="20" />
     <servers />
   </component>
   <component name="Vcs.Log.Tabs.Properties">
@@ -265,7 +293,9 @@
     <MESSAGE value="dunder init update" />
     <MESSAGE value="fixed authors and url for pip show" />
     <MESSAGE value="version update" />
+    <MESSAGE value="readme typo fixes" />
     <MESSAGE value="minor update" />
-    <option name="LAST_COMMIT_MESSAGE" value="minor update" />
+    <MESSAGE value="release_ports: Externalizing logger's config to a user's app. &#10;timers: improve code, docstring and type hinting&#10;README updates IAW with the above changes &#10;Version update: 0.4.0" />
+    <option name="LAST_COMMIT_MESSAGE" value="release_ports: Externalizing logger's config to a user's app. &#10;timers: improve code, docstring and type hinting&#10;README updates IAW with the above changes &#10;Version update: 0.4.0" />
   </component>
 </project>

{nano_dev_utils-0.3.4 → nano_dev_utils-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nano_dev_utils
-Version: 0.3.4
+Version: 0.4.1
 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
@@ -24,16 +24,17 @@ This module provides a `Timer` class for measuring the execution time of code bl
 
 #### `Timer` Class
 
-* **`__init__(self, precision=4, verbose=False)`**: Initializes a `Timer` instance.
-    * `precision` (int, optional): The number of decimal places to record and 
-    * display time durations. Defaults to 4.
-    * `verbose` (bool, optional): If `True`, the function's arguments and keyword
-    * arguments will be included in the printed timing output. Defaults to `False`.
+* **`__init__(self, precision: int = 4, verbose: 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`.
 
-* **`timeit(self, func)`**: A decorator that measures the execution time of the decorated function.
-    * When the decorated function is called, this decorator records the start and end times,
-    * calculates the total execution time, prints the function name and execution time 
-    * (optionally including arguments if `verbose` is `True`), and returns the result of the original function.
+* **`timeit(self, func: Callable[P, R]) -> Callable[P, R]`**:   
+      Decorator that times function execution with automatic unit scaling.   
+    * When the decorated function is called, this decorator records the start and end times,   
+      calculates the total execution time, prints the function name and execution    
+      time (optionally including arguments), and returns the result of the original function.
 
 #### Example Usage:
 
@@ -66,7 +67,7 @@ This module provides an `Importer` class for lazy loading and caching module imp
 * **`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 the cached instance.
+    * 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:
@@ -90,34 +91,42 @@ 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.
+listening on specified TCP ports.    
+It supports Windows, Linux, and macOS.
 
 #### `PortsRelease` Class
 
-* **`__init__(self, default_ports: Optional[list[int]] = None)`**: 
+* **`__init__(self, default_ports: list[int] | None = None)`**: 
 * Initializes a `PortsRelease` instance.
-    * `default_ports` (`list[int]`, *optional*): A list of default ports to manage. 
-    * If not provided, it defaults to `[6277, 6274]`.
+    * `default_ports`: A list of default ports to manage. If not provided, it defaults to `[6277, 6274]`.
 
-* **`get_pid_by_port(port: int) -> Optional[int]`**: A static method that attempts to 
-* find the process ID (PID) listening on the given `port`. It uses platform-specific 
-* commands (`netstat`, `ss`, `lsof`). Returns the PID if found, otherwise `None`. 
+* **`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(pid: int) -> bool`**: A static method that attempts to kill the process 
-* with the given `pid`. It uses platform-specific commands (`taskkill`, `kill -9`). 
+* **`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: Optional[list[int]] = None) -> None`**: Releases all processes
-* listening on the specified `ports`.
-    * `ports` (`list[int]`, *optional*): 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. 
+* **`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
-from src.nano_dev_utils.release_ports import PortsRelease
+import logging
+from nano_dev_utils import PortsRelease
+
+# in case you're interested in logging 
+logging.basicConfig(filename='port release.log',
+                    level=logging.INFO,  # specify here desire level, e.g. DEBUG etc.
+                    format='%(asctime)s - %(levelname)s: %(message)s',
+                    datefmt='%d-%m-%Y %H:%M:%S')
 
 # Create an instance with default ports
 port_releaser = PortsRelease()

{nano_dev_utils-0.3.4 → nano_dev_utils-0.4.1}/README.md

@@ -10,16 +10,17 @@ This module provides a `Timer` class for measuring the execution time of code bl
 
 #### `Timer` Class
 
-* **`__init__(self, precision=4, verbose=False)`**: Initializes a `Timer` instance.
-    * `precision` (int, optional): The number of decimal places to record and 
-    * display time durations. Defaults to 4.
-    * `verbose` (bool, optional): If `True`, the function's arguments and keyword
-    * arguments will be included in the printed timing output. Defaults to `False`.
-
-* **`timeit(self, func)`**: A decorator that measures the execution time of the decorated function.
-    * When the decorated function is called, this decorator records the start and end times,
-    * calculates the total execution time, prints the function name and execution time 
-    * (optionally including arguments if `verbose` is `True`), and returns the result of the original function.
+* **`__init__(self, precision: int = 4, verbose: 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`.
+
+* **`timeit(self, func: Callable[P, R]) -> Callable[P, R]`**:   
+      Decorator that times function execution with automatic unit scaling.   
+    * When the decorated function is called, this decorator records the start and end times,   
+      calculates the total execution time, prints the function name and execution    
+      time (optionally including arguments), and returns the result of the original function.
 
 #### Example Usage:
 
@@ -52,7 +53,7 @@ This module provides an `Importer` class for lazy loading and caching module imp
 * **`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 the cached instance.
+    * 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:
@@ -76,34 +77,42 @@ 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.
+listening on specified TCP ports.    
+It supports Windows, Linux, and macOS.
 
 #### `PortsRelease` Class
 
-* **`__init__(self, default_ports: Optional[list[int]] = None)`**: 
+* **`__init__(self, default_ports: list[int] | None = None)`**: 
 * Initializes a `PortsRelease` instance.
-    * `default_ports` (`list[int]`, *optional*): A list of default ports to manage. 
-    * If not provided, it defaults to `[6277, 6274]`.
+    * `default_ports`: A list of default ports to manage. If not provided, it defaults to `[6277, 6274]`.
 
-* **`get_pid_by_port(port: int) -> Optional[int]`**: A static method that attempts to 
-* find the process ID (PID) listening on the given `port`. It uses platform-specific 
-* commands (`netstat`, `ss`, `lsof`). Returns the PID if found, otherwise `None`. 
+* **`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(pid: int) -> bool`**: A static method that attempts to kill the process 
-* with the given `pid`. It uses platform-specific commands (`taskkill`, `kill -9`). 
+* **`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: Optional[list[int]] = None) -> None`**: Releases all processes
-* listening on the specified `ports`.
-    * `ports` (`list[int]`, *optional*): 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. 
+* **`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
-from src.nano_dev_utils.release_ports import PortsRelease
+import logging
+from nano_dev_utils import PortsRelease
+
+# in case you're interested in logging 
+logging.basicConfig(filename='port release.log',
+                    level=logging.INFO,  # specify here desire level, e.g. DEBUG etc.
+                    format='%(asctime)s - %(levelname)s: %(message)s',
+                    datefmt='%d-%m-%Y %H:%M:%S')
 
 # Create an instance with default ports
 port_releaser = PortsRelease()

{nano_dev_utils-0.3.4 → nano_dev_utils-0.4.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "nano_dev_utils"
-version = "0.3.4"
+version = "0.4.1"
 
 authors = [
   { name="Yaron Dayan", email="yaronday77@gmail.com" },

{nano_dev_utils-0.3.4 → nano_dev_utils-0.4.1}/src/nano_dev_utils/release_ports.py

@@ -2,12 +2,8 @@ import platform
 import subprocess
 import logging
 
-
-logging.basicConfig(filename='port release.log',
-                    level=logging.INFO,
-                    format='%(asctime)s - %(levelname)s: %(message)s',
-                    datefmt='%d-%m-%Y %H:%M:%S')
 lgr = logging.getLogger(__name__)
+"""Module-level logger. Configure using logging.basicConfig() in your application."""
 
 PROXY_SERVER = 6277
 INSPECTOR_CLIENT = 6274
@@ -152,5 +148,4 @@ class PortsRelease:
                 else:
                     lgr.error(self._log_terminate_failed(pid=pid, port=port))
         except Exception as e:
-            lgr.error(self._log_unexpected_error(e))
-
+            lgr.error(self._log_unexpected_error(e))

nano_dev_utils-0.4.1/src/nano_dev_utils/timers.py

@@ -0,0 +1,39 @@
+from functools import wraps
+import time
+from typing import Callable, ParamSpec, TypeVar
+P = ParamSpec('P')
+R = TypeVar('R')
+
+
+class Timer:
+    def __init__(self, precision=4, verbose=False):
+        self.precision = precision
+        self.verbose = verbose
+        self.units = [
+            (1e9, 's'),
+            (1e6, 'ms'),
+            (1e3, 'μs'),
+            (1.0, 'ns')
+        ]
+
+    def timeit(self, func: Callable[P, R]) -> Callable[P, R]:
+        """Decorator that times function execution with automatic unit scaling."""
+        @wraps(func)
+        def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+            start = time.perf_counter_ns()
+            result = func(*args, **kwargs)
+            elapsed = time.perf_counter_ns() - start
+
+            value = elapsed
+            unit = 'ns'
+
+            for divisor, unit in self.units:
+                if elapsed >= divisor or unit == 'ns':
+                    value = elapsed / divisor
+                    break
+
+            extra_info = f'{args} {kwargs} ' if self.verbose else ''
+            print(f'{func.__name__} {extra_info}took {value:.{self.precision}f} [{unit}]')
+            return result
+
+        return wrapper

{nano_dev_utils-0.3.4 → nano_dev_utils-0.4.1}/tests/testing_release_ports.py

@@ -173,12 +173,13 @@ class TestPortsRelease(unittest.TestCase):
 
     def test_get_pid_by_port_unexpected_exception(self):
         with patch('platform.system', return_value='Linux'):
-            with patch('subprocess.Popen', side_effect=Exception("Unexpected")):
+            err = Exception("Unexpected")
+            with patch('subprocess.Popen', side_effect=err):
                 port = 1234
                 pid = self.ports_release.get_pid_by_port(port)
                 self.assertIsNone(pid)
-                self.mock_logger.error.assert_called_once_with("An unexpected "
-                                                               "error occurred: Unexpected")
+                self.mock_logger.error.assert_called_once_with(f'An unexpected '
+                                                               f'error occurred: {err}')
 
     def test_kill_process_success(self):
         with patch('platform.system', return_value='Linux'):

nano_dev_utils-0.3.4/src/nano_dev_utils/timers.py

@@ -1,35 +0,0 @@
-from functools import wraps
-import time
-
-
-class Timer:
-    def __init__(self, precision=4, verbose=False):
-        self.precision = precision
-        self.verbose = verbose
-
-    def timeit(self, func):
-        @wraps(func)
-        def timeit_wrapper(*args, **kwargs):
-            start_time = time.perf_counter_ns()
-            result = func(*args, **kwargs)
-            end_time = time.perf_counter_ns()
-            total_ns = end_time - start_time
-
-            if total_ns < 1_000:  # 1μs
-                value = total_ns
-                unit = "ns"
-            elif total_ns < 1_000_000:  # < 1ms
-                value = total_ns / 1_000
-                unit = "μs"
-            elif total_ns < 1_000_000_000:  # < 1s
-                value = total_ns / 1_000_000
-                unit = "ms"
-            else:
-                value = total_ns / 1_000_000_000
-                unit = "s"
-
-            extra_info = f'{args} {kwargs} ' if self.verbose else ''
-            print(f'{func.__name__} {extra_info}took {value:.{self.precision}f} [{unit}]')
-            return result
-
-        return timeit_wrapper