ures 2.3.0__tar.gz → 2.4.0__tar.gz

ures-2.4.0/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: ures
+Version: 2.4.0
+Summary: Utility library for research and development: Docker workflows, Markdown and Zettelkasten, data structures, and core file/network/string/time helpers.
+License: MIT
+License-File: LICENSE
+Keywords: utilization,Research Tool,Python
+Author: stone
+Author-email: github@stone-bo.com
+Requires-Python: >=3.11,<4.0
+Classifier: Development Status :: 1 - Planning
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Requires-Dist: beautifulsoup4 (>=4.13.4,<5.0.0)
+Requires-Dist: bibtexparser (>=2.0.0b8,<3.0.0)
+Requires-Dist: docker (>=7.1.0,<8.0.0)
+Requires-Dist: onepassword-sdk (>=0.3.1,<0.4.0)
+Requires-Dist: pycountry (>=24.6.1,<25.0.0)
+Requires-Dist: pydantic (>=2.10.6,<3.0.0)
+Requires-Dist: pyperclip (>=1.9.0,<2.0.0)
+Requires-Dist: python-frontmatter (>=1.1.0,<2.0.0)
+Requires-Dist: requests (>=2.32.5,<3.0.0)
+Requires-Dist: sortedcontainers (>=2.4.0,<3.0.0)
+Requires-Dist: tqdm (>=4.67.1,<5.0.0)
+Requires-Dist: unidecode (>=1.4.0,<2.0.0)
+Project-URL: Documentation, https://stone-home.github.io/Python-URes/
+Project-URL: Homepage, https://stone-home.github.io/Python-URes/
+Project-URL: Repository, https://github.com/stone-home/Python-URes
+Description-Content-Type: text/markdown
+
+# Utility for Research (URes)
+
+[![semantic-release: angular](https://img.shields.io/badge/semantic--release-angular-e10079?logo=semantic-release)](https://github.com/stone-home/Python-URes)
+[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://github.com/pre-commit/pre-commit)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/stone-home/Python-URes/blob/main/LICENSE)
+[![Super-Linter](https://github.com/stone-home/Python-URes/actions/workflows/linter.yaml/badge.svg)](https://github.com/stone-home/Python-URes/actions/workflows/linter.yaml)
+[![Trufflehog](https://github.com/stone-home/Python-URes/actions/workflows/secret-check.yaml/badge.svg)](https://github.com/stone-home/Python-URes/actions/workflows/secret-check.yaml)
+[![Code Testing](https://github.com/stone-home/Python-URes/actions/workflows/test.yaml/badge.svg)](https://github.com/stone-home/Python-URes/actions/workflows/test.yaml)
+
+---
+
+## Overview
+
+URes (Utility for Research) is a Python library that centralizes **reusable utilities for research and development**. It provides batteries-included helpers for Docker workflows, Markdown and Zettelkasten notes, data structures, filesystem and network tasks, time/date conversion, string manipulation, and more.
+
+## Key Features
+
+- **Docker management**: Build, run, and orchestrate Docker images and containers with structured configuration objects.
+- **Markdown & Zettelkasten**: Work with Markdown files and front matter, and manage Zettelkasten-style notes with required metadata.
+- **Data structures**: Use tree and bi-directional link structures for organizing and traversing complex data.
+- **Core utilities**: File, time/date, string, secrets, and network helpers used across projects.
+- **Literature tooling**: Search across literature sources and manage citation data (when those modules are enabled).
+
+
+
+## Installation
+
+```bash
+pip install ures
+```
+
+## Modules
+
+### Docker
+
+The `ures.docker` module provides a high-level interface for managing Docker images and containers.
+
+**Key Features**:
+
+  - Programmatically build Docker images from a `BuildConfig` object.
+  - Run containers with detailed runtime configurations using `RuntimeConfig`.
+  - Orchestrate the building of multiple images with dependencies using `ImageOrchestrator`.
+
+**Example**:
+
+```python
+from ures.docker import Image, BuildConfig, Containers
+
+# Define build configuration
+build_config = BuildConfig(
+    base_image="python:3.10-slim",
+    python_dependencies=["flask", "gunicorn"],
+    copies=[{"src": "./app", "dest": "/app"}],
+    entrypoint=["gunicorn", "-b", "0.0.0.0:80", "app:app"]
+)
+
+# Build the image
+image = Image("my-web-app")
+image.build_image(build_config, dest=".")
+
+# Run the container
+containers = Containers(image)
+container = containers.create()
+containers.run()
+```
+
+### Markdown & Zettelkasten
+
+The `ures.markdown` module offers tools for working with Markdown files, including YAML front matter. The `Zettelkasten` class builds on this for note-taking with structured metadata.
+
+- `MarkdownDocument`: Load, create, and manipulate Markdown files with front matter.
+- `Zettelkasten`: Create Zettelkasten notes with required fields such as `title`, `type`, and `tags`.
+
+### Data structures
+
+The `ures.data_structure` module provides reusable data structures:
+
+- `TreeNode`: A tree structure with methods for adding, removing, and traversing nodes.
+- `BiDirectional`: A bi-directional linked list for forward and backward traversal.
+
+### Core utilities
+
+- `ures.files`: File system helpers (recursive file listing, filtering by name, listing directories, creating temp folders).
+- `ures.timedate`: Time/date conversion helpers (datetimes and Unix timestamps to formatted strings, getting the current time).
+- `ures.string`: String utilities such as Zettelkasten-style IDs, unique IDs, memory-size formatting, and capitalization.
+- `ures.secrets`: `SecureKeyManager` for managing API keys and other secrets via different storage methods.
+- `ures.network`: IP and subnet helpers (validation, containment checks, and IP generation from subnets).
+
+### Literature tooling (optional)
+
+If you use the literature search and citation modules, URes can also help with:
+
+- **Literature search**: Configuration-driven multi-source paper search, with adapters and caching.
+- **Literature citation**: Extractors and helpers to manage citation data and apply citation rules.
+
+## Development
+
+To contribute to URes, please follow these steps:
+
+1.  Clone the repository:
+    ```bash
+    git clone https://github.com/stone-home/Python-URes.git
+    ```
+2.  Install the dependencies:
+    ```bash
+    cd Python-URes
+    poetry install
+    ```
+3.  Run the tests:
+    ```bash
+    poetry run pytest
+    ```
+
+## License
+
+This project is licensed under the MIT License – see the [LICENSE](https://github.com/stone-home/Python-URes/blob/main/LICENSE) file for details.
+

ures-2.4.0/docs/index.md

@@ -0,0 +1,117 @@
+# Utility for Research (URes)
+
+[![semantic-release: angular](https://img.shields.io/badge/semantic--release-angular-e10079?logo=semantic-release)](https://github.com/stone-home/Python-URes)
+[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://github.com/pre-commit/pre-commit)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/stone-home/Python-URes/blob/main/LICENSE)
+[![Super-Linter](https://github.com/stone-home/Python-URes/actions/workflows/linter.yaml/badge.svg)](https://github.com/stone-home/Python-URes/actions/workflows/linter.yaml)
+[![Trufflehog](https://github.com/stone-home/Python-URes/actions/workflows/secret-check.yaml/badge.svg)](https://github.com/stone-home/Python-URes/actions/workflows/secret-check.yaml)
+[![Code Testing](https://github.com/stone-home/Python-URes/actions/workflows/test.yaml/badge.svg)](https://github.com/stone-home/Python-URes/actions/workflows/test.yaml)
+
+---
+
+## Overview
+
+URes (Utility for Research) is a Python library that centralizes **reusable utilities for research and development**. It provides batteries-included helpers for Docker workflows, Markdown and Zettelkasten notes, data structures, filesystem and network tasks, time/date conversion, string manipulation, and more.
+
+## Key Features
+
+- **Docker management**: Build, run, and orchestrate Docker images and containers with structured configuration objects.
+- **Markdown & Zettelkasten**: Work with Markdown files and front matter, and manage Zettelkasten-style notes with required metadata.
+- **Data structures**: Use tree and bi-directional link structures for organizing and traversing complex data.
+- **Core utilities**: File, time/date, string, secrets, and network helpers used across projects.
+- **Literature tooling**: Search across literature sources and manage citation data (when those modules are enabled).
+
+
+
+## Installation
+
+```bash
+pip install ures
+```
+
+## Modules
+
+### Docker
+
+The `ures.docker` module provides a high-level interface for managing Docker images and containers.
+
+**Key Features**:
+
+  - Programmatically build Docker images from a `BuildConfig` object.
+  - Run containers with detailed runtime configurations using `RuntimeConfig`.
+  - Orchestrate the building of multiple images with dependencies using `ImageOrchestrator`.
+
+**Example**:
+
+```python
+from ures.docker import Image, BuildConfig, Containers
+
+# Define build configuration
+build_config = BuildConfig(
+    base_image="python:3.10-slim",
+    python_dependencies=["flask", "gunicorn"],
+    copies=[{"src": "./app", "dest": "/app"}],
+    entrypoint=["gunicorn", "-b", "0.0.0.0:80", "app:app"]
+)
+
+# Build the image
+image = Image("my-web-app")
+image.build_image(build_config, dest=".")
+
+# Run the container
+containers = Containers(image)
+container = containers.create()
+containers.run()
+```
+
+### Markdown & Zettelkasten
+
+The `ures.markdown` module offers tools for working with Markdown files, including YAML front matter. The `Zettelkasten` class builds on this for note-taking with structured metadata.
+
+- `MarkdownDocument`: Load, create, and manipulate Markdown files with front matter.
+- `Zettelkasten`: Create Zettelkasten notes with required fields such as `title`, `type`, and `tags`.
+
+### Data structures
+
+The `ures.data_structure` module provides reusable data structures:
+
+- `TreeNode`: A tree structure with methods for adding, removing, and traversing nodes.
+- `BiDirectional`: A bi-directional linked list for forward and backward traversal.
+
+### Core utilities
+
+- `ures.files`: File system helpers (recursive file listing, filtering by name, listing directories, creating temp folders).
+- `ures.timedate`: Time/date conversion helpers (datetimes and Unix timestamps to formatted strings, getting the current time).
+- `ures.string`: String utilities such as Zettelkasten-style IDs, unique IDs, memory-size formatting, and capitalization.
+- `ures.secrets`: `SecureKeyManager` for managing API keys and other secrets via different storage methods.
+- `ures.network`: IP and subnet helpers (validation, containment checks, and IP generation from subnets).
+
+### Literature tooling (optional)
+
+If you use the literature search and citation modules, URes can also help with:
+
+- **Literature search**: Configuration-driven multi-source paper search, with adapters and caching.
+- **Literature citation**: Extractors and helpers to manage citation data and apply citation rules.
+
+## Development
+
+To contribute to URes, please follow these steps:
+
+1.  Clone the repository:
+    ```bash
+    git clone https://github.com/stone-home/Python-URes.git
+    ```
+2.  Install the dependencies:
+    ```bash
+    cd Python-URes
+    poetry install
+    ```
+3.  Run the tests:
+    ```bash
+    poetry run pytest
+    ```
+
+## License
+
+This project is licensed under the MIT License – see the [LICENSE](https://github.com/stone-home/Python-URes/blob/main/LICENSE) file for details.

{ures-2.3.0 → ures-2.4.0}/pyproject.toml

@@ -1,10 +1,12 @@
 [tool.poetry]
 name = "ures"
-version = "2.3.0"
-description = "The project is designed to provide standard utilization functions for improving the reusability of frequently used functions."
+version = "2.4.0"
+description = "Utility library for research and development: Docker workflows, Markdown and Zettelkasten, data structures, and core file/network/string/time helpers."
 authors = ["stone <github@stone-bo.com>"]
 license = "MIT"
 readme = "docs/index.md"
+homepage = "https://stone-home.github.io/Python-URes/"
+documentation = "https://stone-home.github.io/Python-URes/"
 repository = "https://github.com/stone-home/Python-URes"
 keywords = [
     "utilization",

{ures-2.3.0 → ures-2.4.0}/ures/data_structure/bi_directional_links.py

@@ -1,9 +1,11 @@
 from __future__ import annotations
 import uuid
-from typing import Any, Optional
+from typing import Any, Generic, Optional, TypeVar, cast
 
+_BiDirectionT = TypeVar("_BiDirectionT", bound="BiDirection")
 
-class BiDirection:
+
+class BiDirection(Generic[_BiDirectionT]):
     def __init__(self, value: Any):
         """
         Create a bi-directional linked node.
@@ -26,13 +28,13 @@ class BiDirection:
             >>> node.next is node
             True
         """
-        self._prev: Optional[BiDirection] = self
-        self._next: Optional[BiDirection] = self
+        self._prev: _BiDirectionT = cast(_BiDirectionT, self)
+        self._next: _BiDirectionT = cast(_BiDirectionT, self)
         self._value: Any = value
         self._id = uuid.uuid4().hex
 
     @property
-    def prev(self) -> BiDirection:
+    def prev(self) -> _BiDirectionT:
         """
         Get the previous node in the linked structure.
 
@@ -47,7 +49,7 @@ class BiDirection:
         return self._prev
 
     @property
-    def next(self) -> BiDirection:
+    def next(self) -> _BiDirectionT:
         """
         Get the next node in the linked structure.
 
@@ -91,7 +93,7 @@ class BiDirection:
         """
         return self._id
 
-    def insert_after(self, node: BiDirection) -> None:
+    def insert_after(self, node: _BiDirectionT) -> None:
         """
         Insert a node immediately after the current node.
 
@@ -117,7 +119,7 @@ class BiDirection:
         self._next._prev = node
         self._next = node
 
-    def insert_before(self, node: BiDirection) -> None:
+    def insert_before(self, node: _BiDirectionT) -> None:
         """
         Insert a node immediately before the current node.
 
@@ -163,10 +165,10 @@ class BiDirection:
         """
         self._prev._next = self._next
         self._next._prev = self._prev
-        self._prev = self
-        self._next = self
+        self._prev = cast(_BiDirectionT, self)
+        self._next = cast(_BiDirectionT, self)
 
-    def search(self, value: Any) -> Optional[BiDirection]:
+    def search(self, value: Any) -> Optional[_BiDirectionT]:
         """
         Search for a node with the specified value in the linked structure.
 
@@ -192,12 +194,12 @@ class BiDirection:
             >>> not_found is None
             True
         """
-        node = self
+        node: _BiDirectionT = cast(_BiDirectionT, self)
         while node.value != value and node.next != self:
             node = node.next
         return node if node.value == value else None
 
-    def __eq__(self, other: BiDirection) -> bool:
+    def __eq__(self, other: _BiDirectionT) -> bool:
         """
         Check equality between two nodes based on their unique IDs.
 
@@ -246,7 +248,7 @@ class BiDirection:
         return f"BiDirection({self.value})"
 
 
-class NonCircularBiLink(BiDirection):
+class NonCircularBiLink(BiDirection["NonCircularBiLink"]):
     __slots__ = ("_prev", "_next", "_value")
 
     def __init__(self, value: Any):

{ures-2.3.0 → ures-2.4.0}/ures/data_structure/tree.py

@@ -1,9 +1,12 @@
 from __future__ import annotations
 import uuid
-from typing import Any, AnyStr, Dict, Iterator, List, Optional
+from typing import Any, Iterator, Generic, TypeVar, cast
 
 
-class TreeNode:
+_TreeNodeT = TypeVar("_TreeNodeT", bound="TreeNode")
+
+
+class TreeNode(Generic[_TreeNodeT]):
     def __init__(self, value: Any):
         """
         Initialize a TreeNode instance.
@@ -15,22 +18,22 @@ class TreeNode:
             None
 
         Example:
-            >>> node = TreeNode("root")
+            >>> node = _TreeNodeT("root")
             >>> node.value
             'root'
         """
-        self._parent: Optional[TreeNode] = None
-        self._children: Dict[AnyStr, TreeNode] = {}
+        self._parent: _TreeNodeT | None = None
+        self._children: dict[str, _TreeNodeT] = {}
         self._value: Any = value
         self._id = uuid.uuid4().hex
 
     @property
-    def parent(self) -> Optional[TreeNode]:
+    def parent(self) -> _TreeNodeT | None:
         """
         Get the parent node of this TreeNode.
 
         Returns:
-            Optional[TreeNode]: The parent node if it exists; otherwise, None.
+            Optional[_TreeNodeT]: The parent node if it exists; otherwise, None.
 
         Example:
             >>> root = TreeNode("root")
@@ -42,12 +45,12 @@ class TreeNode:
         return self._parent
 
     @property
-    def children(self) -> Dict[AnyStr, TreeNode]:
+    def children(self) -> dict[str, _TreeNodeT]:
         """
         Get the dictionary of child nodes.
 
         Returns:
-            Dict[AnyStr, TreeNode]: A dictionary mapping each child's unique ID to its TreeNode instance.
+            dict[str, _TreeNodeT]: A dictionary mapping each child's unique ID to its TreeNode instance.
 
         Example:
             >>> root = TreeNode("root")
@@ -103,7 +106,7 @@ class TreeNode:
         """
         return self._id
 
-    def add_child(self, child: TreeNode):
+    def add_child(self, child: _TreeNodeT):
         """
         Add a child node to the current node.
 
@@ -123,7 +126,7 @@ class TreeNode:
             >>> child.parent is root
             True
         """
-        if child.id not in self.children.keys():
+        if child.id not in self.children:
             self._children[child.id] = child
             child.set_parent(self)
 
@@ -148,11 +151,11 @@ class TreeNode:
             >>> child.parent is None
             True
         """
-        if child.id in self.children.keys():
+        if child.id in self.children:
             self._children.pop(child.id)
             child.set_parent(None)
 
-    def set_parent(self, parent: Optional[TreeNode]):
+    def set_parent(self, parent: _TreeNodeT | None):
         """
         Set the parent of the current node.
 
@@ -160,7 +163,7 @@ class TreeNode:
         the new parent.
 
         Args:
-            parent (Optional[TreeNode]): The new parent node. If None, the node will have no parent.
+            parent (TreeNode | None): The new parent node. If None, the node will have no parent.
 
         Returns:
             None
@@ -199,7 +202,7 @@ class TreeNode:
             yield current
             current = current.parent
 
-    def forward_stack(self, **kwargs) -> List[List[Any]]:
+    def forward_stack(self, **kwargs) -> list[list[Any]]:
         """
         Get all forward paths from the current node to each leaf node.
 
@@ -211,7 +214,7 @@ class TreeNode:
             attr (str, optional): The attribute name to extract from each node. Defaults to None.
 
         Returns:
-            List[List[Any]]: A list of paths, where each path is a list of nodes or attribute values from the
+            list[list[Any]]: A list of paths, where each path is a list of nodes or attribute values from the
                              current node to a leaf node.
 
         Example:
@@ -225,10 +228,10 @@ class TreeNode:
             [['child1', 'root'], ['child2', 'root']]  # Order may vary
         """
         all_paths = []
-        self._dfs(self, [], all_paths, **kwargs)
+        self._dfs(cast(_TreeNodeT, self), [], all_paths, **kwargs)
         return all_paths
 
-    def _dfs(self, node: TreeNode, current_path: list, all_paths: list, **kwargs):
+    def _dfs(self, node: _TreeNodeT, current_path: list, all_paths: list, **kwargs):
         """
         Recursively perform depth-first search (DFS) to find all paths from the given node to leaf nodes.
 

{ures-2.3.0 → ures-2.4.0}/ures/files.py

@@ -1,9 +1,11 @@
+import logging
 import os
 import tempfile
-from typing import List, Optional
 
+logger = logging.getLogger(__name__)
 
-def get_file_paths(directory: str) -> List[str]:
+
+def get_file_paths(directory: str) -> list[str]:
     """
     Retrieve all file paths within the specified directory and its subdirectories.
 
@@ -14,7 +16,7 @@ def get_file_paths(directory: str) -> List[str]:
         directory (str): The directory path to search in.
 
     Returns:
-        List[str]: A list containing the absolute paths of all files found.
+        list[str]: A list containing the absolute paths of all files found.
 
     Example:
         >>> paths = get_file_paths("/path/to/directory")
@@ -31,7 +33,7 @@ def get_file_paths(directory: str) -> List[str]:
     return file_paths
 
 
-def filter_files(part_file_name: str, directory: str, fuzz: bool = True) -> List[str]:
+def filter_files(part_file_name: str, directory: str, fuzz: bool = True) -> list[str]:
     """
     Retrieve file paths in the specified directory that match a given file name pattern.
 
@@ -46,7 +48,7 @@ def filter_files(part_file_name: str, directory: str, fuzz: bool = True) -> List
             returns only files with an exact name match. Defaults to True.
 
     Returns:
-        List[str]: A list of file paths that match the search criteria.
+        list[str]: A list of file paths that match the search criteria.
 
     Example:
         >>> # Assuming "/tmp/test" contains files "example.txt" and "sample.txt"
@@ -69,7 +71,7 @@ def filter_files(part_file_name: str, directory: str, fuzz: bool = True) -> List
         ]
 
 
-def list_directories(path: str) -> Optional[List[str]]:
+def list_directories(path: str) -> list[str] | None:
     """
     List all subdirectories in the specified path.
 
@@ -80,16 +82,15 @@ def list_directories(path: str) -> Optional[List[str]]:
         path (str): The path where directories should be listed.
 
     Returns:
-        Optional[List[str]]: A list of directory names if the path exists; otherwise, None.
+        list[str] | None: A list of directory names if the path exists; otherwise, None.
 
     Example:
         >>> dirs = list_directories("/tmp")
         >>> isinstance(dirs, list) or dirs is None
         True
     """
-    # Ensure the path exists.
     if not os.path.exists(path):
-        print("The specified path does not exist.")
+        logger.warning("The specified path does not exist: %s", path)
         return None
 
     # List all entries in the path.

{ures-2.3.0 → ures-2.4.0}/ures/literature/citation/middlewares.py

@@ -186,7 +186,7 @@ class TypeNormalizationMiddleware(CitationMiddleware):
     """Normalize entry types (conference -> inproceedings, etc.)"""
 
     def transform_entry(self, entry: Entry, *args, **kwargs) -> Entry:
-        new_type = self.rule_register.get_defulat_bib_type_mapping().get(
+        new_type = self.rule_register.get_default_bib_type_mapping().get(
             entry.entry_type.lower(), entry.entry_type
         )
         entry.entry_type = new_type

{ures-2.3.0 → ures-2.4.0}/ures/literature/citation/rules/__init__.py

@@ -29,7 +29,7 @@ class BibRuleRegister:
             "langid": "language",
         }
 
-    def get_defulat_bib_type_mapping(self) -> Dict[str, str]:
+    def get_default_bib_type_mapping(self) -> Dict[str, str]:
         return {
             "conference": "inproceedings",
             "incollection": "inproceedings",  # Some publishers treat book chapters as conf papers

{ures-2.3.0 → ures-2.4.0}/ures/markdown/zettelkasten.py

@@ -84,7 +84,8 @@ class Zettelkasten(MarkdownDocument):
 
         _params = dict(post.metadata)
         n_type = _params.get("type", None)
-        del _params["type"]
+        if n_type is not None:
+            del _params["type"]
         _params["n_type"] = n_type
 
         keywords = ["title", "n_type", "url", "tags", "aliases"]

{ures-2.3.0 → ures-2.4.0}/ures/string.py

@@ -39,7 +39,7 @@ def unique_id() -> str:
     return uuid.uuid4().hex
 
 
-def format_memory(nbytes: int) -> str:
+def format_memory(nbytes: int | None) -> str:
     """
     Format a memory size into a human-readable string.
 
@@ -47,7 +47,7 @@ def format_memory(nbytes: int) -> str:
     with two decimal places of precision. If the provided value is None, it returns "0 bytes".
 
     Args:
-            nbytes (int): The memory size in bytes.
+            nbytes (int | None): The memory size in bytes, or None for "0 bytes".
 
     Returns:
             str: The memory size in a human-readable format.
@@ -98,7 +98,7 @@ def capitalize_string(string: str, separator: str = " ") -> str:
     return separator.join([item.capitalize() for item in string.split(separator)])
 
 
-def string2date(date_string) -> dict[str, int | str | None]:
+def string2date(date_string: str) -> dict[str, int | str | None]:
     """
     Parses various date string formats ('YYYY', 'YYYY-MM', 'YYYY-MM-DD')
     and returns a dictionary with the month as a three-letter abbreviation.

{ures-2.3.0 → ures-2.4.0}/ures/timedate.py

@@ -1,4 +1,5 @@
 import datetime
+import sys
 
 
 def datetime_converter(
@@ -99,8 +100,6 @@ def time_now(iso8601: bool = True, format: str = "%Y%m%d-%H%M%S") -> str:
         >>> time_now(iso8601=False, format="%H:%M:%S")
         '14:35:22'
     """
-    import sys
-
     if sys.version_info[:2] == (3, 10):
         _time = datetime.datetime.now(datetime.timezone.utc)
     else:

{ures-2.3.0 → ures-2.4.0}/ures/tools/decorator.py

@@ -2,7 +2,7 @@ import logging
 from functools import wraps
 
 
-logger = logging.getLogger(__file__)
+logger = logging.getLogger(__name__)
 
 
 def check_instance_variable(variable_name):

{ures-2.3.0 → ures-2.4.0}/ures/tools/enum.py

@@ -136,7 +136,7 @@ class EnumManipulator:
             return member.value
         return None
 
-    def filter_by(self, keyword: str, field: str = None) -> list:
+    def filter_by(self, keyword: str, field: str | None = None) -> list:
         """
         Filter and return keys from the Enum where the specified keyword matches.
 

ures-2.3.0/PKG-INFO

@@ -1,183 +0,0 @@
-Metadata-Version: 2.3
-Name: ures
-Version: 2.3.0
-Summary: The project is designed to provide standard utilization functions for improving the reusability of frequently used functions.
-License: MIT
-Keywords: utilization,Research Tool,Python
-Author: stone
-Author-email: github@stone-bo.com
-Requires-Python: >=3.11,<4.0
-Classifier: Development Status :: 1 - Planning
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: Implementation :: PyPy
-Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Classifier: Topic :: Utilities
-Requires-Dist: beautifulsoup4 (>=4.13.4,<5.0.0)
-Requires-Dist: bibtexparser (>=2.0.0b8,<3.0.0)
-Requires-Dist: docker (>=7.1.0,<8.0.0)
-Requires-Dist: onepassword-sdk (>=0.3.1,<0.4.0)
-Requires-Dist: pycountry (>=24.6.1,<25.0.0)
-Requires-Dist: pydantic (>=2.10.6,<3.0.0)
-Requires-Dist: pyperclip (>=1.9.0,<2.0.0)
-Requires-Dist: python-frontmatter (>=1.1.0,<2.0.0)
-Requires-Dist: requests (>=2.32.5,<3.0.0)
-Requires-Dist: sortedcontainers (>=2.4.0,<3.0.0)
-Requires-Dist: tqdm (>=4.67.1,<5.0.0)
-Requires-Dist: unidecode (>=1.4.0,<2.0.0)
-Project-URL: Repository, https://github.com/stone-home/Python-URes
-Description-Content-Type: text/markdown
-
-# Utility for Research (URes)
-
-[![semantic-release: angular](https://img.shields.io/badge/semantic--release-angular-e10079?logo=semantic-release)](https://github.com/semantic-release/semantic-release)
-[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://github.com/pre-commit/pre-commit)
-[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Super-Linter](https://github.com/stone-home/Python-URes/actions/workflows/linter.yaml/badge.svg)](https://github.com/stone-home/Python-URes/actions/workflows/linter.yaml)
-[![Trufflehog](https://github.com/stone-home/Python-URes/actions/workflows/secret-check.yaml/badge.svg)](https://github.com/stone-home/Python-URes/actions/workflows/secret-check.yaml)
-[![Code Testing](https://github.com/stone-home/Python-URes/actions/workflows/test.yaml/badge.svg)](https://github.com/stone-home/Python-URes/actions/workflows/test.yaml)
-
-
----
-## Overview
-
-URes (Utility for Research) is a versatile Python library that simplifies common research and development tasks. It offers a wide range of modules to handle everything from Docker container management to advanced data visualization and file operations.
-
-## Key Features
-
-  - **Docker Management**: Build, run, and manage Docker images and containers with an intuitive Python interface.
-  - **Markdown and Zettelkasten**: Create, manipulate, and organize Markdown documents, with support for the Zettelkasten note-taking method.
-  - **Data Structures**: Implement and use advanced data structures like Trees and Bi-Directional Links for complex data organization.
-  - **File and Network Utilities**: Simplify file system operations and network-related tasks with a collection of helper functions.
-  - **Time and Date Converters**: Easily convert between different time and date formats, including ISO 8601 and Unix timestamps.
-  - **String Manipulation**: A set of functions for common string operations, such as capitalization and unique ID generation.
-  - **Advanced Plotting**: A comprehensive, multi-backend visualization library for scientific research, data analysis, and machine learning.
-
-
-## Installation
-
-```bash
-pip install ures
-```
-
-## Modules
-
-### Docker
-
-The `ures.docker` module provides a high-level interface for managing Docker images and containers.
-
-**Key Features**:
-
-  - Programmatically build Docker images from a `BuildConfig` object.
-  - Run containers with detailed runtime configurations using `RuntimeConfig`.
-  - Orchestrate the building of multiple images with dependencies using `ImageOrchestrator`.
-
-**Example**:
-
-```python
-from ures.docker import Image, BuildConfig, Containers
-
-# Define build configuration
-build_config = BuildConfig(
-    base_image="python:3.10-slim",
-    python_dependencies=["flask", "gunicorn"],
-    copies=[{"src": "./app", "dest": "/app"}],
-    entrypoint=["gunicorn", "-b", "0.0.0.0:80", "app:app"]
-)
-
-# Build the image
-image = Image("my-web-app")
-image.build_image(build_config, dest=".")
-
-# Run the container
-containers = Containers(image)
-container = containers.create()
-containers.run()
-```
-
-### Markdown
-
-The `ures.markdown` module offers tools for working with Markdown files, including those with YAML front matter. The `Zettelkasten` class extends this functionality for note-taking.
-
-**Key Features**:
-
-  - Load, create, and manipulate Markdown files with `MarkdownDocument`.
-  - Manage YAML front matter with support for nested keys.
-  - Implement the Zettelkasten method with the `Zettelkasten` class, which includes mandatory metadata fields like `title`, `type`, and `tags`.
-
-**Example**:
-
-```python
-from ures.markdown import Zettelkasten
-
-# Create a new Zettelkasten note
-note = Zettelkasten(
-    title="My Research Note",
-    n_type="permanent",
-    tags=["research", "python"],
-    aliases=["research-note"]
-)
-
-# Add content
-note.add_content("This is a sample research note.")
-
-# Save to file
-note.save("my_note.md")
-```
-
-### Data Structures
-
-The `ures.data_structure` module provides implementations of advanced data structures.
-
-  - **TreeNode**: A tree data structure with methods for adding, removing, and traversing nodes.
-  - **BiDirectional**: A bi-directional linked list that allows for easy traversal in both forward and backward directions.
-
-### File and Network Utilities
-
-  - **`ures.files`**: A collection of functions for file system operations, such as recursively getting file paths, filtering files, and managing temporary directories.
-  - **`ures.network`**: Helper functions for network-related tasks, including IP address validation and generation.
-
-### Time and Date Converters
-
-The `ures.timedate` module provides functions for converting between different time and date formats.
-
-  - `datetime_converter()`: Converts a `datetime` object to a formatted string (ISO 8601 or custom).
-  - `timestamp_converter()`: Converts a Unix timestamp to a formatted string.
-  - `time_now()`: Returns the current time as a formatted string.
-
-### String Manipulation
-
-The `ures.string` module offers a variety of string utility functions.
-
-  - `zettelkasten_id()`: Generates a unique ID suitable for Zettelkasten notes.
-  - `unique_id()`: Creates a standard unique identifier.
-  - `format_memory()`: Formats a memory size into a human-readable string.
-  - `capitalize_string()`: Capitalizes each word in a string.
-
-## Development
-
-To contribute to URes, please follow these steps:
-
-1.  Clone the repository:
-    ```bash
-    git clone https://github.com/stone-home/Python-URes.git
-    ```
-2.  Install the dependencies:
-    ```bash
-    cd Python-URes
-    poetry install
-    ```
-3.  Run the tests:
-    ```bash
-    poetry run pytest
-    ```
-
-## License
-
-This project is licensed under the MIT License - see the [LICENSE](https://www.google.com/search?q=LICENSE) file for details.
-

ures-2.3.0/docs/index.md

@@ -1,148 +0,0 @@
-# Utility for Research (URes)
-
-[![semantic-release: angular](https://img.shields.io/badge/semantic--release-angular-e10079?logo=semantic-release)](https://github.com/semantic-release/semantic-release)
-[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://github.com/pre-commit/pre-commit)
-[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Super-Linter](https://github.com/stone-home/Python-URes/actions/workflows/linter.yaml/badge.svg)](https://github.com/stone-home/Python-URes/actions/workflows/linter.yaml)
-[![Trufflehog](https://github.com/stone-home/Python-URes/actions/workflows/secret-check.yaml/badge.svg)](https://github.com/stone-home/Python-URes/actions/workflows/secret-check.yaml)
-[![Code Testing](https://github.com/stone-home/Python-URes/actions/workflows/test.yaml/badge.svg)](https://github.com/stone-home/Python-URes/actions/workflows/test.yaml)
-
-
----
-## Overview
-
-URes (Utility for Research) is a versatile Python library that simplifies common research and development tasks. It offers a wide range of modules to handle everything from Docker container management to advanced data visualization and file operations.
-
-## Key Features
-
-  - **Docker Management**: Build, run, and manage Docker images and containers with an intuitive Python interface.
-  - **Markdown and Zettelkasten**: Create, manipulate, and organize Markdown documents, with support for the Zettelkasten note-taking method.
-  - **Data Structures**: Implement and use advanced data structures like Trees and Bi-Directional Links for complex data organization.
-  - **File and Network Utilities**: Simplify file system operations and network-related tasks with a collection of helper functions.
-  - **Time and Date Converters**: Easily convert between different time and date formats, including ISO 8601 and Unix timestamps.
-  - **String Manipulation**: A set of functions for common string operations, such as capitalization and unique ID generation.
-  - **Advanced Plotting**: A comprehensive, multi-backend visualization library for scientific research, data analysis, and machine learning.
-
-
-## Installation
-
-```bash
-pip install ures
-```
-
-## Modules
-
-### Docker
-
-The `ures.docker` module provides a high-level interface for managing Docker images and containers.
-
-**Key Features**:
-
-  - Programmatically build Docker images from a `BuildConfig` object.
-  - Run containers with detailed runtime configurations using `RuntimeConfig`.
-  - Orchestrate the building of multiple images with dependencies using `ImageOrchestrator`.
-
-**Example**:
-
-```python
-from ures.docker import Image, BuildConfig, Containers
-
-# Define build configuration
-build_config = BuildConfig(
-    base_image="python:3.10-slim",
-    python_dependencies=["flask", "gunicorn"],
-    copies=[{"src": "./app", "dest": "/app"}],
-    entrypoint=["gunicorn", "-b", "0.0.0.0:80", "app:app"]
-)
-
-# Build the image
-image = Image("my-web-app")
-image.build_image(build_config, dest=".")
-
-# Run the container
-containers = Containers(image)
-container = containers.create()
-containers.run()
-```
-
-### Markdown
-
-The `ures.markdown` module offers tools for working with Markdown files, including those with YAML front matter. The `Zettelkasten` class extends this functionality for note-taking.
-
-**Key Features**:
-
-  - Load, create, and manipulate Markdown files with `MarkdownDocument`.
-  - Manage YAML front matter with support for nested keys.
-  - Implement the Zettelkasten method with the `Zettelkasten` class, which includes mandatory metadata fields like `title`, `type`, and `tags`.
-
-**Example**:
-
-```python
-from ures.markdown import Zettelkasten
-
-# Create a new Zettelkasten note
-note = Zettelkasten(
-    title="My Research Note",
-    n_type="permanent",
-    tags=["research", "python"],
-    aliases=["research-note"]
-)
-
-# Add content
-note.add_content("This is a sample research note.")
-
-# Save to file
-note.save("my_note.md")
-```
-
-### Data Structures
-
-The `ures.data_structure` module provides implementations of advanced data structures.
-
-  - **TreeNode**: A tree data structure with methods for adding, removing, and traversing nodes.
-  - **BiDirectional**: A bi-directional linked list that allows for easy traversal in both forward and backward directions.
-
-### File and Network Utilities
-
-  - **`ures.files`**: A collection of functions for file system operations, such as recursively getting file paths, filtering files, and managing temporary directories.
-  - **`ures.network`**: Helper functions for network-related tasks, including IP address validation and generation.
-
-### Time and Date Converters
-
-The `ures.timedate` module provides functions for converting between different time and date formats.
-
-  - `datetime_converter()`: Converts a `datetime` object to a formatted string (ISO 8601 or custom).
-  - `timestamp_converter()`: Converts a Unix timestamp to a formatted string.
-  - `time_now()`: Returns the current time as a formatted string.
-
-### String Manipulation
-
-The `ures.string` module offers a variety of string utility functions.
-
-  - `zettelkasten_id()`: Generates a unique ID suitable for Zettelkasten notes.
-  - `unique_id()`: Creates a standard unique identifier.
-  - `format_memory()`: Formats a memory size into a human-readable string.
-  - `capitalize_string()`: Capitalizes each word in a string.
-
-## Development
-
-To contribute to URes, please follow these steps:
-
-1.  Clone the repository:
-    ```bash
-    git clone https://github.com/stone-home/Python-URes.git
-    ```
-2.  Install the dependencies:
-    ```bash
-    cd Python-URes
-    poetry install
-    ```
-3.  Run the tests:
-    ```bash
-    poetry run pytest
-    ```
-
-## License
-
-This project is licensed under the MIT License - see the [LICENSE](https://www.google.com/search?q=LICENSE) file for details.