ures 1.3.1__tar.gz

ures-1.3.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 stone-home
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ures-1.3.1/PKG-INFO

@@ -0,0 +1,34 @@
+Metadata-Version: 2.1
+Name: ures
+Version: 1.3.1
+Summary: The project is designed to provide standard utilization functions for improving the reusability of frequently used functions.
+Home-page: https://github.com/stone-home/Python-URes
+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: python-frontmatter (>=1.1.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)
+

ures-1.3.1/README.md

@@ -0,0 +1,9 @@
+# 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)

ures-1.3.1/pyproject.toml

@@ -0,0 +1,65 @@
+[tool.poetry]
+name = "ures"
+version = "1.3.1"
+description = "The project is designed to provide standard utilization functions for improving the reusability of frequently used functions."
+authors = ["stone <github@stone-bo.com>"]
+license = "MIT"
+readme = "README.md"
+repository = "https://github.com/stone-home/Python-URes"
+keywords = [
+    "utilization",
+    "Research Tool",
+    "Python"
+]
+classifiers = [
+    "Development Status :: 1 - Planning",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: Implementation :: PyPy",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Utilities",
+]
+packages = [
+    { include = "ures"},
+]
+exclude = [
+    "tests",
+    "docs",
+    "examples",
+    "dist",
+    "build",
+    "ures.egg-info",
+    ".git",
+    ".gitignore",
+    ".github",
+    ".pre-commit-config.yaml",
+    "commitlint.config.js",
+    "run_ut.sh",
+    ".env"
+]
+
+[tool.poetry.dependencies]
+python = "^3.11"
+python-frontmatter = "^1.1.0"
+
+
+[tool.poetry.group.test.dependencies]
+pytest = "^8.3.4"
+pytest-cov = "^6.0.0"
+
+
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+
+# pyproject.toml
+[tool.pytest.ini_options]
+minversion = "8.0"
+addopts = "-q --cache-clear"
+testpaths = [
+    "tests",
+]

ures-1.3.1/ures/data_structure/__init__.py

@@ -0,0 +1,4 @@
+from .tree import TreeNode
+from .bi_directional_links import BiDirection
+
+__all__ = ["TreeNode", "BiDirection"]

ures-1.3.1/ures/data_structure/bi_directional_links.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+import uuid
+from typing import Any, AnyStr, Dict, Optional
+
+
+class BiDirection:
+    def __init__(self, value: Any):
+        """Create a bi-directional link node.
+
+        Args:
+            value (Any): The value of the node.
+        """
+        self._prev: Optional[BiDirection] = self
+        self._next: Optional[BiDirection] = self
+        self._value: Any = value
+        self._id = uuid.uuid4().hex
+
+    @property
+    def prev(self) -> BiDirection:
+        return self._prev
+
+    @property
+    def next(self) -> BiDirection:
+        return self._next
+
+    @property
+    def value(self) -> Any:
+        return self._value
+
+    @property
+    def id(self) -> str:
+        return self._id
+
+    def insert_after(self, node: BiDirection):
+        """Insert a node after the current node.
+
+        Args:
+            node (BiDirection): The node to be inserted.
+
+        Returns:
+            None
+
+        """
+        node._prev = self
+        node._next = self._next
+        self._next._prev = node
+        self._next = node
+
+    def insert_before(self, node: BiDirection):
+        """Insert a node before the current node.
+
+        Args:
+            node (BiDirection): The node to be inserted.
+
+        Returns:
+            None
+
+        """
+        node._prev = self._prev
+        node._next = self
+        self._prev._next = node
+        self._prev = node
+
+    def remove(self):
+        """Remove the current node.
+
+        Returns:
+            None
+        """
+        self._prev._next = self._next
+        self._next._prev = self._prev
+        self._prev = self
+        self._next = self
+
+    def search(self, value: Any) -> Optional[BiDirection]:
+        """Search a node by value.
+
+        Args:
+            value (Any): The value to be searched.
+
+        Returns:
+            Optional[BiDirection]: The node with the value.
+        """
+        node = 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:
+        """Check if two nodes are equal."""
+        return self.id == other.id
+
+    def __str__(self):
+        """Return the string representation of the node."""
+        return str(self.value)
+
+    def __repr__(self):
+        """Return the string representation of the node."""
+        return f"BiDirection({self.value})"

ures-1.3.1/ures/data_structure/tree.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+import uuid
+from typing import Any, AnyStr, Dict, Iterator, List, Optional
+
+
+class TreeNode:
+    def __init__(self, value: Any):
+        """Initialize a TreeNode object.
+
+        Args:
+            value (Any): The value of the node.
+        """
+        self._parent: Optional[TreeNode] = None
+        self._children: Dict[AnyStr, TreeNode] = {}
+        self._value: Any = value
+        self._id = uuid.uuid4().hex
+
+    @property
+    def parent(self) -> Optional[TreeNode]:
+        return self._parent
+
+    @property
+    def children(self) -> Dict[AnyStr, TreeNode]:
+        return self._children
+
+    @property
+    def is_leaf(self) -> bool:
+        return len(self.children) == 0
+
+    @property
+    def value(self) -> Any:
+        return self._value
+
+    @property
+    def id(self) -> str:
+        return self._id
+
+    def add_child(self, child: TreeNode):
+        """Add a child node to the current node.
+
+        Args:
+            child (TreeNode): The child node to be added.
+
+        Returns:
+            None
+        """
+        if child.id not in self.children.keys():
+            self._children[child.id] = child
+            child.set_parent(self)
+
+    def remove_child(self, child: TreeNode):
+        """Remove a child node from the current node.
+
+        Args:
+            child (TreeNode): The child node to be removed.
+
+        Returns:
+            None
+
+        """
+        if child.id in self.children.keys():
+            self._children.pop(child.id)
+            child.set_parent(None)
+
+    def set_parent(self, parent: Optional[TreeNode]):
+        """Set the parent node of the current node.
+
+        Args:
+            parent (Optional[TreeNode]): The parent node to be set.
+
+        Returns:
+            None
+        """
+        if parent is not None:
+            if isinstance(self.parent, TreeNode):
+                self.parent.remove_child(self)
+        self._parent = parent
+
+    def backward_stack(self) -> Iterator[TreeNode]:
+        """Get the backward stack of the current node. The direction is from the current node to the root node."""
+        current = self
+        while current is not None:
+            yield current
+            current = current.parent
+
+    def forward_stack(self, **kwargs) -> List[List[Any]]:
+        """Get the forward stack of the current node. The direction is from the current node to the leaf node."""
+        all_paths = []
+        self._dfs(self, [], all_paths, **kwargs)
+        return all_paths
+
+    def _dfs(self, node: TreeNode, current_path: list, all_paths: list, **kwargs):
+        assert isinstance(node, TreeNode)
+        _attr = kwargs.get("attr", None)
+        _key = node
+        if _attr is not None:
+            _key = getattr(node, _attr)
+        current_path.append(_key)
+
+        if not node.children:
+            all_paths.append(list(current_path))
+        else:
+            for child in node.children.values():
+                self._dfs(child, current_path, all_paths, **kwargs)
+        # pop up the last index of the current path, and go back to the parent node
+        # Example:
+        # current_path = [1, 2, 3]
+        # after pop: [1, 2]
+        current_path.pop()

ures-1.3.1/ures/files.py

@@ -0,0 +1,100 @@
+import os
+import tempfile
+from typing import List, Optional
+
+
+def get_file_paths(directory) -> List[str]:
+    """Get all file paths in the specified directory.
+
+    Args:
+        directory (str): the directory path
+
+    Returns:
+        List[str]: a list of file paths
+
+    """
+    file_paths = []
+    # Walk through the directory and its subdirectories
+    for root, _, files in os.walk(directory):
+        for file in files:
+            # Join the root path with the file name to get the absolute path
+            file_path = os.path.join(root, file)
+            file_paths.append(str(file_path))
+
+    return file_paths
+
+
+def filter_files(part_file_name: str, directory: str, fuzz: bool = True) -> List[str]:
+    """Fetch all file path that contains the specified part of file name.
+
+    Args:
+        part_file_name (str): the part of file name or keyword
+        directory (str): the directory path
+        fuzz (bool): if True, return all files that contain the part of file name. Defaults to True.
+
+    Returns:
+        List[str]: a list of file paths
+    """
+    file_paths = fetch_file_paths(directory)
+    if fuzz:
+        return [
+            str(file_path)
+            for file_path in file_paths
+            if part_file_name in os.path.basename(str(file_path))
+        ]
+    else:
+        return [
+            str(file_path)
+            for file_path in file_paths
+            if part_file_name == os.path.basename(str(file_path))
+        ]
+
+
+def list_directories(path: str) -> Optional[List[str]]:
+    """list all directories in the specified path.
+
+    Args:
+        path (str): the path to a directories
+
+    Returns:
+        Optional[List[str]]: a list of directories or None if the path does not exist
+
+    """
+    # Ensure the path exists
+    if not os.path.exists(path):
+        print("The specified path does not exist.")
+        return None
+
+    # List all entries in the path
+    entries = os.listdir(path)
+    directories = [
+        entry for entry in entries if os.path.isdir(os.path.join(path, entry))
+    ]
+
+    return directories
+
+
+def get_temp_folder() -> str:
+    """Get a temporary folder.
+
+    Returns:
+        str: a temporary folder path
+
+    """
+    return tempfile.TemporaryDirectory().name
+
+
+def get_temp_dir_with_specific_path(*args):
+    """Get a temporary directory with a specific path.
+
+    Args:
+        *args: Variable length argument list to specify the subdirectory path.
+
+    Returns:
+        str: The path of the created temporary directory.
+    """
+    temp_dir = tempfile.gettempdir()
+    flame_temp = os.path.join(temp_dir, *args)
+    if not os.path.isdir(flame_temp):
+        os.makedirs(flame_temp, exist_ok=True)
+    return flame_temp

ures-1.3.1/ures/markdown/__init__.py

@@ -0,0 +1,4 @@
+from .manipulator import MarkdownDocument
+from .zettelkasten import Zettelkasten
+
+__all__ = ["MarkdownDocument", "Zettelkasten"]

ures-1.3.1/ures/markdown/manipulator.py

@@ -0,0 +1,464 @@
+import frontmatter
+from typing import Any, Dict, Optional, List, AnyStr
+import os
+from copy import deepcopy
+
+
+class MarkdownDocument:
+    """
+    A low-level class for manipulating Markdown files with front matter.
+
+    This class provides methods to add and modify Markdown content and front matter,
+    supporting nested structures in front matter (e.g., dictionaries within YAML front matter).
+    """
+
+    MANDATORY_FIELDS: List[AnyStr] = []
+
+    def __init__(self, content: str = "", metadata: Optional[Dict[str, Any]] = None):
+        """
+        Initializes a new MarkdownDocument instance.
+
+        Args:
+            content (str): The Markdown content. Defaults to an empty string.
+            metadata (Optional[Dict[str, Any]]): The front matter metadata as a dictionary. Defaults to None.
+
+        Example:
+            >>> doc = MarkdownDocument(
+            ...     content="# Hello World",
+            ...     metadata={"title": "Greeting", "tags": ["intro", "welcome"]}
+            ... )
+        """
+        if metadata is None:
+            metadata = {}
+        self.post = frontmatter.Post(content, **metadata)
+
+    @classmethod
+    def from_file(cls, file_path: str) -> "MarkdownDocument":
+        """
+        Creates a MarkdownDocument instance by loading a Markdown file.
+
+        Args:
+            file_path (str): The path to the Markdown file.
+
+        Returns:
+            MarkdownDocument: An instance representing the loaded Markdown file.
+
+        Raises:
+            FileNotFoundError: If the specified file does not exist.
+            frontmatter.InvalidFrontMatterError: If the front matter is malformed.
+        """
+        if not os.path.isfile(file_path):
+            raise FileNotFoundError(f"The file '{file_path}' does not exist.")
+
+        with open(file_path, "r", encoding="utf-8") as f:
+            post = frontmatter.load(f)
+        return cls(content=post.content, metadata=deepcopy(post.metadata))
+
+    @property
+    def content(self) -> str:
+        """
+        Retrieves the Markdown content.
+
+        Returns:
+            str: The Markdown content.
+
+        Example:
+            >>> doc = MarkdownDocument(content="# Hello World")
+            >>> doc.content
+            "# Hello World"
+        """
+        return self.post.content
+
+    @content.setter
+    def content(self, new_content: str) -> None:
+        """
+        Sets the Markdown content.
+
+        Args:
+            new_content (str): The new Markdown content.
+
+        Example:
+            >>> doc = MarkdownDocument()
+            >>> doc.content = "# New Title"
+        """
+        self.post.content = new_content
+
+    @property
+    def metadata(self) -> Dict[str, Any]:
+        """
+        Retrieves the front matter metadata.
+
+        Returns:
+            Dict[str, Any]: The metadata dictionary.
+
+        Example:
+            >>> doc = MarkdownDocument(metadata={"title": "Greeting", "tags": ["intro", "welcome"]})
+            >>> doc.metadata
+            {"title": "Greeting", "tags": ["intro", "welcome"]}
+        """
+        return self.post.metadata
+
+    @metadata.setter
+    def metadata(self, new_metadata: Dict[str, Any]) -> None:
+        """
+        Sets the front matter metadata.
+
+        Args:
+            new_metadata (Dict[str, Any]): The new metadata dictionary.
+
+        Example:
+            >>> doc = MarkdownDocument()
+            >>> doc.metadata = {"title": "New Greeting", "tags": ["updated"]}
+        """
+        self.post.metadata = new_metadata
+
+    def add_content(self, content: str, append: bool = True) -> None:
+        """
+        Adds content to the Markdown document.
+
+        Args:
+            content (str): The Markdown content to add.
+            append (bool): If True, appends to existing content; otherwise, prepends.
+                           Defaults to True.
+
+        Example:
+            >>> doc = MarkdownDocument()
+            >>> doc.add_content("# Introduction")
+            >>> doc.add_content("Some introductory text.", append=True)
+        """
+        if append:
+            if self.post.content:
+                self.post.content += "\n" + content
+            else:
+                self.post.content = content
+        else:
+            if self.post.content:
+                self.post.content = content + "\n" + self.post.content
+            else:
+                self.post.content = content
+
+    def set_frontmatter(
+        self, key_path: str, value: Any, overwrite: bool = True
+    ) -> None:
+        """
+        Sets a front matter key to a specified value. Supports nested keys using dot notation,
+        including mixed types such as dictionaries within lists.
+
+        Args:
+            key_path (str): The front matter key path. Use dot notation for nested keys
+                            (e.g., "author.name" or "sections.0.title").
+            value (Any): The value to set for the key.
+            overwrite (bool): If True, overwrites the existing value; otherwise, appends to lists
+                              or creates new entries in lists. Defaults to True.
+
+        Example:
+            >>> doc = MarkdownDocument()
+            >>> doc.set_frontmatter("author.name", "John Doe")
+            >>> doc.set_frontmatter("author.contact.email", "john@example.com")
+            >>> doc.set_frontmatter("sections.0.title", "Introduction")
+            >>> doc.set_frontmatter("sections.0.content", "Welcome to the introduction.")
+            >>> doc.set_frontmatter("sections.1.title", "Conclusion")
+            >>> doc.set_frontmatter("sections.1.content", "Wrapping up.")
+        """
+        keys = key_path.split(".")
+        current = self.post.metadata
+
+        for i, key in enumerate(keys):
+            is_last = i == len(keys) - 1
+            # Determine if the current key is meant to be a list index
+            if key.isdigit():
+                index = int(key)
+                if not isinstance(current, list):
+                    if overwrite:
+                        # Initialize as list
+                        parent = self.post.metadata
+                        for k in keys[:i]:
+                            if k.isdigit():
+                                parent = parent[int(k)]
+                            else:
+                                parent = parent[k]
+                        parent[int(keys[i - 1])] = []
+                        current = parent[int(keys[i - 1])]
+                    else:
+                        raise TypeError(
+                            f"Expected list at {'.'.join(keys[:i])}, found {type(current).__name__}"
+                        )
+                # Extend the list if necessary
+                while len(current) <= index:
+                    current.append({})
+                if is_last:
+                    if isinstance(current[index], list) and not overwrite:
+                        current[index].append(value)
+                    elif isinstance(current[index], dict):
+                        if isinstance(value, dict):
+                            current[index].update(value)
+                        else:
+                            current[index]["value"] = value
+                    elif not overwrite:
+                        current[index] = [current[index], value]
+                    else:
+                        current[index] = value
+                else:
+                    if not isinstance(current[index], (dict, list)):
+                        # Initialize as dict or list based on next key
+                        next_key = keys[i + 1]
+                        if next_key.isdigit():
+                            current[index] = []
+                        else:
+                            current[index] = {}
+                    current = current[index]
+            else:
+                if not isinstance(current, dict):
+                    if overwrite:
+                        # Initialize as dict
+                        parent = self.post.metadata
+                        for k in keys[:i]:
+                            if k.isdigit():
+                                parent = parent[int(k)]
+                            else:
+                                parent = parent[k]
+                        parent[keys[i - 1]] = {}
+                        current = parent[keys[i - 1]]
+                    else:
+                        raise TypeError(
+                            f"Expected dict at {'.'.join(keys[:i])}, found {type(current).__name__}"
+                        )
+                if is_last:
+                    if key in current:
+                        if isinstance(current[key], list) and not overwrite:
+                            current[key].append(value)
+                        elif isinstance(current[key], dict):
+                            if isinstance(value, dict):
+                                current[key].update(value)
+                            else:
+                                current[key]["value"] = value
+                        elif not overwrite:
+                            current[key] = [current[key], value]
+                        else:
+                            current[key] = value
+                    else:
+                        current[key] = value
+                else:
+                    if key not in current or not isinstance(current[key], (dict, list)):
+                        # Initialize as dict or list based on next key
+                        next_key = keys[i + 1]
+                        if next_key.isdigit():
+                            current[key] = []
+                        else:
+                            current[key] = {}
+                    current = current[key]
+
+    def get_frontmatter(self, key_path: str) -> Any:
+        """
+        Retrieves the value of a front matter key. Supports nested keys using dot notation,
+        including list indices.
+
+        Args:
+            key_path (str): The front matter key path. Use dot notation for nested keys
+                            (e.g., "author.name" or "sections.0.title").
+
+        Returns:
+            Any: The value associated with the key, or None if the key does not exist.
+
+        Example:
+            >>> doc = MarkdownDocument(
+            ...     metadata={
+            ...         "author": {"name": "John Doe", "contact": {"email": "john@example.com"}},
+            ...         "sections": [
+            ...             {"title": "Introduction", "content": "Welcome."},
+            ...             {"title": "Conclusion", "content": "Goodbye."}
+            ...         ]
+            ...     }
+            ... )
+            >>> doc.get_frontmatter("author.name")
+            "John Doe"
+            >>> doc.get_frontmatter("sections.0.title")
+            "Introduction"
+            >>> doc.get_frontmatter("sections.1.content")
+            "Goodbye."
+        """
+        keys = key_path.split(".")
+        metadata = self.post.metadata
+
+        for key in keys:
+            if isinstance(metadata, dict):
+                metadata = metadata.get(key, None)
+            elif isinstance(metadata, list):
+                if key.isdigit():
+                    index = int(key)
+                    if 0 <= index < len(metadata):
+                        metadata = metadata[index]
+                    else:
+                        return None
+                else:
+                    return None
+            else:
+                return None
+
+            if metadata is None:
+                return None
+
+        return metadata
+
+    def remove_frontmatter(self, key_path: str) -> None:
+        """
+        Removes a front matter key. Supports nested keys using dot notation,
+        including list indices.
+
+        Args:
+            key_path (str): The front matter key path to remove. Use dot notation for nested keys
+                            (e.g., "author.contact.email" or "sections.0.title").
+
+        Example:
+            >>> doc = MarkdownDocument(
+            ...     metadata={
+            ...         "author": {"name": "John Doe", "contact": {"email": "john@example.com"}},
+            ...         "sections": [
+            ...             {"title": "Introduction", "content": "Welcome."},
+            ...             {"title": "Conclusion", "content": "Goodbye."}
+            ...         ]
+            ...     }
+            ... )
+            >>> doc.remove_frontmatter("author.contact.email")
+            >>> doc.get_frontmatter("author.contact.email") is None
+            True
+            >>> doc.remove_frontmatter("sections.1.title")
+            >>> doc.get_frontmatter("sections.1.title") is None
+            True
+        """
+        keys = key_path.split(".")
+        metadata = self.post.metadata
+
+        for i, key in enumerate(keys):
+            is_last = i == len(keys) - 1
+            if isinstance(metadata, dict):
+                if key not in metadata:
+                    return  # Key path does not exist; nothing to remove
+                if is_last:
+                    del metadata[key]
+                    return
+                metadata = metadata[key]
+            elif isinstance(metadata, list):
+                if key.isdigit():
+                    index = int(key)
+                    if 0 <= index < len(metadata):
+                        if is_last:
+                            del metadata[index]
+                            return
+                        metadata = metadata[index]
+                    else:
+                        return  # Index out of range; nothing to remove
+                else:
+                    return  # Invalid key for list; nothing to remove
+            else:
+                return  # Neither dict nor list; nothing to remove
+
+    def to_markdown(self) -> str:
+        """
+        Serializes the MarkdownDocument to a Markdown-formatted string, including front matter.
+
+        Returns:
+            str: The complete Markdown content with front matter.
+
+        ERROR:
+            ValueError: If the front matter is missing mandatory fields.
+
+        Example:
+            >>> doc = MarkdownDocument(
+            ...     content="# Hello World",
+            ...     metadata={"title": "Greeting", "tags": ["intro", "welcome"]}
+            ... )
+            >>> print(doc.to_markdown())
+            ---
+            title: Greeting
+            tags:
+              - intro
+              - welcome
+            ---
+
+            # Hello World
+        """
+        self.validation_frontmatter()
+        return frontmatter.dumps(self.post)
+
+    def save(self, file_path: str) -> None:
+        """
+        Saves the MarkdownDocument to a specified file.
+
+        Args:
+            file_path (str): The path where the Markdown file will be saved.
+
+        Example:
+            >>> doc = MarkdownDocument(
+            ...     content="# Hello World",
+            ...     metadata={"title": "Greeting", "tags": ["intro", "welcome"]}
+            ... )
+            >>> doc.save_to_file("greeting.md")
+        """
+        markdown_str = self.to_markdown()
+        with open(file_path, "w", encoding="utf-8") as f:
+            f.write(markdown_str)
+
+    def load_from_file(self, file_path: str) -> None:
+        """
+        Loads Markdown content and front matter from a specified file into the current instance.
+
+        Args:
+            file_path (str): The path to the Markdown file to load.
+
+        Raises:
+            FileNotFoundError: If the specified file does not exist.
+            frontmatter.InvalidFrontMatterError: If the front matter is malformed.
+
+        Example:
+            >>> doc = MarkdownDocument()
+            >>> doc.load_from_file("existing.md")
+        """
+        if not os.path.isfile(file_path):
+            raise FileNotFoundError(f"The file '{file_path}' does not exist.")
+
+        with open(file_path, "r", encoding="utf-8") as f:
+            post = frontmatter.load(f)
+
+        self.post.content = post.content
+        self.post.metadata = deepcopy(post.metadata)
+
+    def clear_content(self) -> None:
+        """
+        Clears all Markdown content, leaving only the front matter.
+
+        Example:
+            >>> doc = MarkdownDocument(content="# Hello World")
+            >>> doc.clear_content()
+            >>> print(doc.content)
+            ""
+        """
+        self.post.content = ""
+
+    def clear_frontmatter(self) -> None:
+        """
+        Clears all front matter metadata, leaving only the Markdown content.
+
+        Example:
+            >>> doc = MarkdownDocument(
+            ...     content="# Hello World",
+            ...     metadata={"title": "Greeting", "tags": ["intro", "welcome"]}
+            ... )
+            >>> doc.clear_frontmatter()
+            >>> print(doc.metadata)
+            {}
+        """
+        self.post.metadata = {}
+
+    def validation_frontmatter(self):
+        """
+        Validate the frontmatter metadata against the mandatory fields.
+        """
+        missing_fields = []
+        for field in self.MANDATORY_FIELDS:
+            if self.get_frontmatter(field) is None:
+                missing_fields.append(field)
+
+        if missing_fields:
+            missing = ", ".join(missing_fields)
+            raise ValueError(f"Missing mandatory front matter fields: {missing}")

ures-1.3.1/ures/markdown/zettelkasten.py

@@ -0,0 +1,155 @@
+import os
+from typing import Optional
+from ures.timedate import time_now
+from ures.string import unique_id
+from .manipulator import MarkdownDocument, frontmatter
+
+
+class Zettelkasten(MarkdownDocument):
+    """
+    Class for handling Zettelkasten markdown files. In my case, a list of mandatory fields is defined in a class
+    variable.
+
+    In Zettelkasten note-taking system, only three types of notes are supported: 'fleeting', 'literature', 'permanent',
+    but I added 'atom' type for my own use.
+    """
+
+    MANDATORY_FIELDS = ["title", "type", "url", "create", "id", "tags", "aliases"]
+    ALLOWED_TYPES = ["fleeting", "literature", "permanent", "atom"]
+
+    def __init__(
+        self,
+        title: str,
+        n_type: str,
+        url: Optional[str] = None,
+        tags: Optional[list] = None,
+        aliases: Optional[list] = None,
+    ):
+        """
+        Initialize a Zettelkasten object
+        Args:
+            title (str): The title of the note.
+            n_type (str): The type of the note, only support 'fleeting', 'literature', 'permanent' and 'atom'.
+            url (str): The url of the note.
+            tags (list): The tags of the note.
+            aliases
+        """
+        if not isinstance(title, str) or not title.strip():
+            raise ValueError("Title must be a non-empty string.")
+        if n_type not in self.ALLOWED_TYPES:
+            raise ValueError(
+                f"Invalid type '{n_type}'. Allowed types are: {', '.join(self.ALLOWED_TYPES)}."
+            )
+        if url is not None and not isinstance(url, str):
+            raise ValueError("URL must be a string.")
+        if tags is not None and not isinstance(tags, list):
+            raise ValueError("Tags must be a list.")
+        if aliases is not None and not isinstance(aliases, list):
+            raise ValueError("Aliases must be a list.")
+
+        _metadata = {
+            "id": unique_id(),
+            "create": time_now(),
+        }
+        super().__init__(metadata=_metadata)
+        self.title = title
+        self.type = n_type
+        self.url = url or ""
+        self.tags = tags or []
+        self.aliases = aliases or []
+
+    @classmethod
+    def from_file(cls, file_path: str) -> "MarkdownDocument":
+        """
+        Creates a MarkdownDocument instance by loading a Markdown file.
+
+        Args:
+            file_path (str): The path to the Markdown file.
+
+        Returns:
+            MarkdownDocument: An instance representing the loaded Markdown file.
+
+        Raises:
+            FileNotFoundError: If the specified file does not exist.
+            frontmatter.InvalidFrontMatterError: If the front matter is malformed.
+        """
+        if not os.path.isfile(file_path):
+            raise FileNotFoundError(f"The file '{file_path}' does not exist.")
+
+        with open(file_path, "r", encoding="utf-8") as f:
+            post = frontmatter.load(f)
+        zk = cls(
+            title=post.metadata.get("title", None),
+            n_type=post.metadata.get("type", None),
+            url=post.metadata.get("url", None),
+            tags=post.metadata.get("tags", None),
+            aliases=post.metadata.get("aliases", None),
+        )
+        zk.metadata["id"] = post.metadata.get("id", zk.metadata["id"])
+        zk.metadata["create"] = post.metadata.get("create", zk.metadata["create"])
+        zk.add_content(post.content)
+        return zk
+
+    @property
+    def title(self) -> str:
+        return self.get_frontmatter("title")
+
+    @title.setter
+    def title(self, value):
+        if not isinstance(value, str) or not value.strip():
+            raise ValueError("Title must be a non-empty string.")
+        self.set_frontmatter("title", value)
+
+    @property
+    def type(self) -> str:
+        return self.get_frontmatter("type")
+
+    @type.setter
+    def type(self, value):
+        if value not in self.ALLOWED_TYPES:
+            raise ValueError(
+                f"Invalid type '{value}'. Allowed types are: {', '.join(self.ALLOWED_TYPES)}."
+            )
+        self.set_frontmatter("type", value)
+
+    @property
+    def url(self) -> str:
+        return self.get_frontmatter("url")
+
+    @url.setter
+    def url(self, value):
+        if not isinstance(value, str):
+            raise ValueError("URL must be a string.")
+        self.set_frontmatter("url", value)
+
+    @property
+    def tags(self) -> list:
+        return self.get_frontmatter("tags")
+
+    @tags.setter
+    def tags(self, value):
+        if not isinstance(value, list):
+            raise ValueError("Tags must be a list.")
+        self.set_frontmatter("tags", value)
+
+    @property
+    def aliases(self) -> list:
+        return self.get_frontmatter("aliases")
+
+    @aliases.setter
+    def aliases(self, value):
+        if not isinstance(value, list):
+            raise ValueError("Aliases must be a list.")
+        self.set_frontmatter("aliases", value)
+
+    def add_tag(self, tag: str):
+        self.tags.append(tag)
+
+    def remove_tag(self, tag: str):
+        self.tags.remove(tag)
+
+    def add_alias(self, alias: str):
+        self.aliases.append(alias)
+
+    def remove_alias(self, alias: str):
+        self.aliases.remove(alias)

ures-1.3.1/ures/network.py

@@ -0,0 +1,36 @@
+import ipaddress
+
+
+def verify_ip_in_subnet(ip, subnet) -> bool:
+    """Verify if an ip address is in a subnet.
+
+    Args:
+        ip (str): an ip address
+        subnet (str): a subnet
+
+    Returns:
+        bool: True if the ip address is in the subnet, False otherwise
+    """
+    ip = ipaddress.ip_address(ip)
+    subnet = ipaddress.ip_network(subnet)
+    return ip in subnet
+
+
+def generate_ip(subnet, last_index):
+    """Generate an ip address based on the subnet and the last index.
+
+    Args:
+        subnet (str): a subnet
+        last_index (int): the last index of the ip address.
+
+    Examples:
+        generate_ip("192.168.0.0/24", 100)
+        # Output: 192.168.0.101
+
+    Returns:
+        str: a new ip address
+
+    """
+    network = ipaddress.ip_network(subnet)
+    new_ip = network.network_address + last_index
+    return str(new_ip)

ures-1.3.1/ures/string.py

@@ -0,0 +1,46 @@
+import uuid
+
+
+def zettelkasten_id() -> str:
+    """Generate an id used for zettelkasten note-taking system only.
+
+    Returns:
+        str: a zettelkasten id
+
+    """
+    _id = uuid.uuid4().hex
+    return f"{_id[:9]}.{_id[-11:]}"
+
+
+def unique_id() -> str:
+    """generate a unique id.
+
+    Returns:
+        str: a unique id
+
+    """
+    return uuid.uuid4().hex
+
+
+def format_memory(nbytes: int) -> str:
+    """Format memory size in human-readable format.
+
+    Args:
+        nbytes (int): the memory size in bytes
+
+    Returns:
+        str: the memory size in human-readable format
+
+    **The function is copied from PyTorch source code.**
+    """
+    KB = 1024
+    MB = 1024 * KB
+    GB = 1024 * MB
+    if abs(nbytes) >= GB:
+        return f"{nbytes * 1.0 / GB:.2f} GB"
+    elif abs(nbytes) >= MB:
+        return f"{nbytes * 1.0 / MB:.2f} MB"
+    elif abs(nbytes) >= KB:
+        return f"{nbytes * 1.0 / KB:.2f} KB"
+    else:
+        return str(nbytes) + " B"

ures-1.3.1/ures/timedate.py

@@ -0,0 +1,57 @@
+import datetime
+
+
+def datetime_converter(
+    time: datetime.datetime, iso8601: bool = True, format: str = "%Y%m%d-%H%M%S"
+) -> str:
+    """COnvert `datetime.datetime` object to iso8601 format or custom format.
+
+    Args:
+        time (datetime.datetime): the time want to be converted
+        iso8601 (bool): if True, return iso8601 format. Defaults to True.
+        format (str): custom format, and it is only available when iso8601 set to false. Defaults to "%Y%m%d-%H%M%S".
+
+    Returns:
+        str: the time in expected format
+    """
+    if iso8601:
+        return time.isoformat() + "Z"
+    else:
+        return time.strftime(format)
+
+
+def timestamp_converter(
+    timestamp: int, iso8601: bool = True, format: str = "%Y%m%d-%H%M%S"
+) -> str:
+    """Convert unix timestamp to iso8601 format or custom format.
+
+    Args:
+        timestamp (int): a unix timestamp
+        iso8601 (bool): if True, return iso8601 format. Defaults to True.
+        format (str): custom format, and it is only available when iso8601 set to false. Defaults to "%Y%m%d-%H%M%S".
+
+    Returns:
+        str: the time in expected format
+    """
+    return datetime_converter(
+        datetime.datetime.fromtimestamp(timestamp),
+        iso8601=iso8601,
+        format=format,
+        # datetime.datetime.utcfromtimestamp(timestamp), iso8601=iso8601, format=format
+    )
+
+
+def time_now(iso8601: bool = True, format: str = "%Y%m%d-%H%M%S") -> str:
+    """Generate a current time in iso8601 format or custom format.
+
+    Args:
+        iso8601 (bool): if True, return iso8601 format. Defaults to True.
+        format (str): custom format, and it is only available when iso8601 set to false. Defaults to "%Y%m%d-%H%M%S".
+
+    Returns:
+        str: the time in expected format
+
+    """
+    return datetime_converter(
+        datetime.datetime.now(datetime.UTC), iso8601=iso8601, format=format
+    )

ures-1.3.1/ures/tools/__init__.py

@@ -0,0 +1,15 @@
+import os
+import importlib
+import pkgutil
+
+package_dir = os.path.dirname(__file__)
+
+for _, module_name, _ in pkgutil.iter_modules([package_dir]):
+    module = importlib.import_module(f".{module_name}", package=__name__)
+
+    for attribute_name in dir(module):
+        attribute = getattr(module, attribute_name)
+        if isinstance(attribute, type) and not attribute_name.startswith("_"):
+            globals()[attribute_name] = attribute
+
+__all__ = [name for name in globals() if not name.startswith("_")]

ures-1.3.1/ures/tools/enum.py

@@ -0,0 +1,97 @@
+from enum import Enum, EnumMeta
+from typing import List, Optional
+
+
+class EnumManipulator:
+    """A class to manipulate Enum object."""
+
+    def __init__(self, input_enum: EnumMeta):
+        """initialize the class.
+
+        Args:
+            input_enum (EnumMeta): an Enum object
+        """
+        self._enum = input_enum
+
+    @property
+    def fetch_enums(self) -> EnumMeta:
+        """Get the Enum object."""
+        return self._enum
+
+    def fetch_keys(self) -> List[str]:
+        """Get all keys in the Enum object."""
+        return self.fetch_enums._member_names_
+
+    def fetch_enum(self, key_name: str) -> Optional[Enum]:
+        """Fetch the Enum object by key name.
+
+        Args:
+            key_name (str): the key name
+
+        Returns:
+            Optional[Enum]: the Enum object or None if the key does not exist
+
+        """
+        key = None
+        for _key in self.fetch_keys():
+            if key_name.lower() == str(_key).lower():
+                key = self.fetch_enums[_key]
+                break
+        return key
+
+    def check_key(self, key_name: str) -> bool:
+        """Check if the key exists in the Enum object.
+
+        Args:
+            key_name (str): the key name
+
+        Returns:
+            bool: True if the key exists, False otherwise
+
+        """
+        return False if self.fetch_enum(key_name) is None else True
+
+    def fetch_value(self, key_name: str):
+        """Fetch the value of the Enum object by key name.
+
+        Args:
+            key_name (str): the key name
+
+        Returns:
+            any: the value of the Enum object or None if the key does not exist
+
+        """
+        key = self.fetch_enum(key_name)
+        value = None
+        if key is not None:
+            value = key.value
+        return value
+
+    def filter_by(self, keyword: str, field: str = None) -> list:
+        """Fetch the key when the keyword is found in the field of the Enum object.
+        If the field is None, the keyword is compared with the value of the Enum object.
+
+        Args:
+            keyword (str): the keyword to search
+            field (str): the field to search. Defaults to None. if not none, the field points to the attribute of the value.
+
+        Returns:
+            list: a list of keys
+
+        """
+        keys = self.fetch_keys()
+        result = []
+        for key in keys:
+            _value = self.fetch_enums[key].value
+            if field is None:
+                if keyword == str(_value):
+                    result.append(key)
+            else:
+                _field_value = getattr(_value, field)
+                if isinstance(_field_value, str):
+                    if keyword.lower() in _field_value.lower():
+                        result.append(key)
+                elif isinstance(_field_value, list):
+                    if keyword.lower() in [str(_).lower() for _ in _field_value]:
+                        result.append(key)
+        return result