comb-utils 0.0.2__tar.gz → 0.1.0__tar.gz

{comb_utils-0.0.2/src/comb_utils.egg-info → comb_utils-0.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: comb_utils
-Version: 0.0.2
+Version: 0.1.0
 Summary: Handy utils for Python projects.
 Author: Kaleb Coberly
 Maintainer-email: kaleb.coberly@gmail.com
@@ -41,7 +41,7 @@ Requires-Dist: coverage[toml]; extra == "test"
 Requires-Dist: pytest; extra == "test"
 Requires-Dist: pytest-cov; extra == "test"
 
-# Basic package template
+# Comb Utils
 
 ## Summary
 
@@ -53,7 +53,6 @@ Some handy utils for Python projects. Repo is made from the `reference_package`
     .github/workflows               GitHub Actions CI/CD workflows.
     docs                            RST docs and doc build staging.
     Makefile                        Dev tools and params. (includes shared/Makefile)
-    src/comb_utils/api              Public and internal API.
     setup.cfg                       Metadata and dependencies.
     shared                          Shared dev tools Git submodule.
     src/comb_utils/lib              Implementation.
@@ -70,12 +69,6 @@ To install the package, run:
 
 See https://pypi.org/project/comb-utils/.
 
-## Library functions
-
-`comb_utils` is a library from which you can import functions. Import the public example function like this: `from comb_utils import wait_a_second`. Or, import the internal version like a power user like this: `from comb_utils.api.internal import wait_a_second`.
-
-Unless you're developing, avoid importing directly from library, like `from comb_utils.lib.example import wait_a_second`.
-
 ## Dev workflow
 
 There are a number of dev tools in the `Makefile`. You can list all the make tools you might want to use:

{comb_utils-0.0.2 → comb_utils-0.1.0}/README.md

@@ -1,4 +1,4 @@
-# Basic package template
+# Comb Utils
 
 ## Summary
 
@@ -10,7 +10,6 @@ Some handy utils for Python projects. Repo is made from the `reference_package`
     .github/workflows               GitHub Actions CI/CD workflows.
     docs                            RST docs and doc build staging.
     Makefile                        Dev tools and params. (includes shared/Makefile)
-    src/comb_utils/api              Public and internal API.
     setup.cfg                       Metadata and dependencies.
     shared                          Shared dev tools Git submodule.
     src/comb_utils/lib              Implementation.
@@ -27,12 +26,6 @@ To install the package, run:
 
 See https://pypi.org/project/comb-utils/.
 
-## Library functions
-
-`comb_utils` is a library from which you can import functions. Import the public example function like this: `from comb_utils import wait_a_second`. Or, import the internal version like a power user like this: `from comb_utils.api.internal import wait_a_second`.
-
-Unless you're developing, avoid importing directly from library, like `from comb_utils.lib.example import wait_a_second`.
-
 ## Dev workflow
 
 There are a number of dev tools in the `Makefile`. You can list all the make tools you might want to use:

{comb_utils-0.0.2 → comb_utils-0.1.0}/setup.cfg

@@ -1,12 +1,12 @@
 [metadata]
 name = comb_utils
-version = 0.0.2
+version = 0.1.0
 description = Handy utils for Python projects.
 long_description = file: README.md
 long_description_content_type = text/markdown
 author = Kaleb Coberly
 maintainer_email = kaleb.coberly@gmail.com
-copyright = 2024, Kaleb Coberly
+copyright = 2025, Kaleb Coberly
 
 [options]
 python_requires = >=3.11

{comb_utils-0.0.2 → comb_utils-0.1.0}/src/comb_utils/__init__.py

@@ -2,7 +2,7 @@
 
 from importlib.metadata import version
 
-from comb_utils.api.public import wait_a_second
+from comb_utils.lib import DocString, ErrorDocString
 
 try:
     __version__: str = version(__name__)

comb_utils-0.1.0/src/comb_utils/lib/__init__.py

@@ -0,0 +1,3 @@
+"""lib init."""
+
+from comb_utils.lib.docs import DocString, ErrorDocString

comb_utils-0.1.0/src/comb_utils/lib/docs.py

@@ -0,0 +1,100 @@
+"""Docstring formatting for sphinx API docs and click CLI help."""
+
+from dataclasses import dataclass
+from typing import Final
+
+from typeguard import typechecked
+
+
+@dataclass
+class ErrorDocString:
+    """Error docstrings.
+
+    Args:
+            error_type: The error type. E.g., "ValueError".
+            docstring: The error docstring. E.g., "When arg `a` is less than 0."
+    """
+
+    error_type: Final[str]
+    docstring: Final[str]
+
+    @typechecked
+    def __init__(self, error_type: str, docstring: str) -> None:
+        """Initialize the error docstring."""
+        self.error_type = error_type
+        self.docstring = docstring
+
+        return
+
+
+# TODO: Move this to a central utils repo. (And combine with Defaults? Include types?)
+class DocString:
+    """Class to format docstrings for public API `sphinx` docs and CLI `click` help.
+
+    Args:
+            opening: The opening docstring.
+            args: Argument names and their docstrings.
+            raises: Objects holding error types with their docstrings.
+            returns: The returns docstrings.
+    """
+
+    opening: str = ""
+    args: dict[str, str] = {}
+    raises: list[ErrorDocString] = []
+    returns: list[str] = []
+
+    @typechecked
+    def __init__(
+        self,
+        opening: str,
+        args: dict[str, str],
+        raises: list[ErrorDocString],
+        returns: list[str],
+    ) -> None:
+        """Initialize the docstring parts."""
+        self.opening = opening
+        self.args = args
+        self.raises = raises
+        self.returns = returns
+
+        return
+
+    @property
+    @typechecked
+    def api_docstring(self) -> str:
+        """Docstring formatted for Sphinx API docs."""
+        parts = [self.opening.strip()]
+
+        if self.args:
+            parts.append("\nArgs:\n")
+            parts.extend([f"  {key}: {value}" for key, value in self.args.items()])
+
+        if self.raises:
+            parts.append("\nRaises:\n")
+            parts.extend(
+                [f"  {error.error_type}: {error.docstring}" for error in self.raises]
+            )
+
+        if self.returns:
+            parts.append("\nReturns:\n")
+            parts.extend([f"  {item}" for item in self.returns])
+
+        return "\n\n".join(parts) + "\n"
+
+    @property
+    @typechecked
+    def cli_docstring(self) -> str:
+        """Docstring formatted for Click CLI help."""
+        parts = [self.opening.strip()]
+
+        if self.raises:
+            parts.append("\nRaises:\n")
+            parts.extend(
+                [f"  {error.error_type}: {error.docstring}" for error in self.raises]
+            )
+
+        if self.returns:
+            parts.append("\nReturns:\n")
+            parts.extend([f"  {item}" for item in self.returns])
+
+        return "\n\n".join(parts) + "\n"

{comb_utils-0.0.2 → comb_utils-0.1.0/src/comb_utils.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: comb_utils
-Version: 0.0.2
+Version: 0.1.0
 Summary: Handy utils for Python projects.
 Author: Kaleb Coberly
 Maintainer-email: kaleb.coberly@gmail.com
@@ -41,7 +41,7 @@ Requires-Dist: coverage[toml]; extra == "test"
 Requires-Dist: pytest; extra == "test"
 Requires-Dist: pytest-cov; extra == "test"
 
-# Basic package template
+# Comb Utils
 
 ## Summary
 
@@ -53,7 +53,6 @@ Some handy utils for Python projects. Repo is made from the `reference_package`
     .github/workflows               GitHub Actions CI/CD workflows.
     docs                            RST docs and doc build staging.
     Makefile                        Dev tools and params. (includes shared/Makefile)
-    src/comb_utils/api              Public and internal API.
     setup.cfg                       Metadata and dependencies.
     shared                          Shared dev tools Git submodule.
     src/comb_utils/lib              Implementation.
@@ -70,12 +69,6 @@ To install the package, run:
 
 See https://pypi.org/project/comb-utils/.
 
-## Library functions
-
-`comb_utils` is a library from which you can import functions. Import the public example function like this: `from comb_utils import wait_a_second`. Or, import the internal version like a power user like this: `from comb_utils.api.internal import wait_a_second`.
-
-Unless you're developing, avoid importing directly from library, like `from comb_utils.lib.example import wait_a_second`.
-
 ## Dev workflow
 
 There are a number of dev tools in the `Makefile`. You can list all the make tools you might want to use:

{comb_utils-0.0.2 → comb_utils-0.1.0}/src/comb_utils.egg-info/SOURCES.txt

@@ -8,8 +8,5 @@ src/comb_utils.egg-info/SOURCES.txt
 src/comb_utils.egg-info/dependency_links.txt
 src/comb_utils.egg-info/requires.txt
 src/comb_utils.egg-info/top_level.txt
-src/comb_utils/api/__init__.py
-src/comb_utils/api/internal.py
-src/comb_utils/api/public.py
 src/comb_utils/lib/__init__.py
-src/comb_utils/lib/example.py
+src/comb_utils/lib/docs.py

comb_utils-0.0.2/src/comb_utils/api/__init__.py

@@ -1 +0,0 @@
-"""Do not define in API, only import."""

comb_utils-0.0.2/src/comb_utils/api/internal.py

@@ -1,25 +0,0 @@
-"""Internal functions overlay library and are typically wrapped by public functions.
-
-This allows us to maintain a separation of API from implementation.
-Internal functions may come with extra options that public functions don't have, say for
-power users and developers who may want to use an existing DB session or something.
-"""
-
-from typeguard import typechecked
-
-from comb_utils.lib import example
-
-
-@typechecked
-def wait_a_second(
-    secs: int = 1, extra_string: str = "Fancy me, calling internal functions."
-) -> None:
-    """Just wait a second, or however many seconds you want.
-
-    Also prints a message with the number you passed, along with any extra message you want.
-
-    Arguments:
-        secs: How many seconds to wait.
-        extra_string: Extra message to add on tail of existing message.
-    """
-    example.wait_a_second(secs=secs, extra_string=extra_string)

comb_utils-0.0.2/src/comb_utils/api/public.py

@@ -1,21 +0,0 @@
-"""Public functions wrap internal functions which wrap library functions.
-
-This allows separation of API from implementation. It also allows a simplified public API
-separate from a more complex internal API with more options for power users.
-"""
-
-from typeguard import typechecked
-
-from comb_utils.api.internal import example
-
-
-@typechecked
-def wait_a_second(secs: int = 1) -> None:
-    """Just wait a second, or however many seconds you want.
-
-    Also prints a message with the number you passed.
-
-    Arguments:
-        secs: How many seconds to wait.
-    """
-    example.wait_a_second(secs=secs)

comb_utils-0.0.2/src/comb_utils/lib/__init__.py

@@ -1 +0,0 @@
-"""lib init."""

comb_utils-0.0.2/src/comb_utils/lib/example.py

@@ -1,16 +0,0 @@
-"""This is an example module."""
-
-import time
-
-
-def wait_a_second(secs: int = 1, extra_string: str = "") -> None:
-    """Just wait a second, or however many seconds you want.
-
-    Also prints a message with the number you passed, along with any extra message you want.
-
-    Arguments:
-        secs: How many seconds to wait.
-        extra_string: Extra message to add on tail of existing message.
-    """
-    print(f"Waiting {secs} seconds.{' ' + extra_string if extra_string else ''}")
-    time.sleep(secs)