comb-utils 0.0.2__py3-none-any.whl

comb_utils/__init__.py

@@ -0,0 +1,12 @@
+"""Top-level init."""
+
+from importlib.metadata import version
+
+from comb_utils.api.public import wait_a_second
+
+try:
+    __version__: str = version(__name__)
+except Exception:
+    __version__ = "unknown"
+
+del version

comb_utils/api/__init__.py

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

comb_utils/api/internal.py

@@ -0,0 +1,25 @@
+"""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/api/public.py

@@ -0,0 +1,21 @@
+"""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/lib/__init__.py

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

comb_utils/lib/example.py

@@ -0,0 +1,16 @@
+"""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)

comb_utils-0.0.2.dist-info/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Kaleb Coberly
+
+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.

comb_utils-0.0.2.dist-info/METADATA

@@ -0,0 +1,142 @@
+Metadata-Version: 2.2
+Name: comb_utils
+Version: 0.0.2
+Summary: Handy utils for Python projects.
+Author: Kaleb Coberly
+Maintainer-email: kaleb.coberly@gmail.com
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typeguard
+Provides-Extra: dev
+Requires-Dist: comb_utils[build]; extra == "dev"
+Requires-Dist: comb_utils[doc]; extra == "dev"
+Requires-Dist: comb_utils[qc]; extra == "dev"
+Requires-Dist: comb_utils[test]; extra == "dev"
+Provides-Extra: build
+Requires-Dist: build; extra == "build"
+Requires-Dist: twine; extra == "build"
+Provides-Extra: doc
+Requires-Dist: furo; extra == "doc"
+Requires-Dist: sphinx; extra == "doc"
+Requires-Dist: sphinx-autodoc-typehints; extra == "doc"
+Provides-Extra: qc
+Requires-Dist: bandit; extra == "qc"
+Requires-Dist: black; extra == "qc"
+Requires-Dist: black[jupyter]; extra == "qc"
+Requires-Dist: flake8; extra == "qc"
+Requires-Dist: flake8-annotations; extra == "qc"
+Requires-Dist: flake8-bandit; extra == "qc"
+Requires-Dist: flake8-black; extra == "qc"
+Requires-Dist: flake8-bugbear; extra == "qc"
+Requires-Dist: flake8-docstrings; extra == "qc"
+Requires-Dist: flake8-isort; extra == "qc"
+Requires-Dist: isort; extra == "qc"
+Requires-Dist: jake; extra == "qc"
+Requires-Dist: pytype; extra == "qc"
+Requires-Dist: comb_utils[test]; extra == "qc"
+Requires-Dist: safety; extra == "qc"
+Provides-Extra: test
+Requires-Dist: coverage[toml]; extra == "test"
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+
+# Basic package template
+
+## Summary
+
+Some handy utils for Python projects. Repo is made from the `reference_package` template repo: https://github.com/crickets-and-comb/reference_package. See the docs: https://crickets-and-comb.github.io/shared_utils/.
+
+## Structure
+
+```bash
+    .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.
+    tests/e2e                       End-to-end tests.
+    test/integration                Integration tests.
+    tests/unit                      Unit tests.
+```
+
+## Installation
+
+To install the package, run:
+
+  $ pip install comb_utils
+
+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:
+
+    $ make list-targets
+
+Go check them out in `Makefile`.
+
+*Note: The dev tools are built around developing on a Mac, so they may not all work on Windows without some modifications.*
+
+### Shared tools setup
+
+When you first clone this repo, you'll need to set up the shared tools Git submodule. Follow the setup directions on that repo's README: https://github.com/crickets-and-comb/shared
+
+#### Updating shared tools
+
+Once you've set up the shared dev tools submodule, you'll want to periodically update it to get updates to the shared tools:
+
+  $ make update-shared
+
+Note that, while you'll be able to run with this updated shared submodule, you'll still want to commit that update to your consuming repo to track that update.
+
+#### Setting Personal Access Token
+
+The shared workflows rely on a Personal Access Token (PAT) (to checkout the submodule so they can use the make targets). You need to create a PAT with repo access and add it to the consuming repo's (`comb_utils` in this case) action secrets as `CHECKOUT_SHARED`. See GitHub for how to set up PATs (hint: check the developer settings on your personal account) and how to add secrets to a repo's actions (hint: check the repo's settings).
+
+Note: Using a PAT tied to a single user like this is less than ideal. Figuring out how to get around this is a welcome security upgrade.
+
+### Dev installation
+
+You'll want this package's site-package files to be the source files in this repo so you can test your changes without having to reinstall. We've got some tools for that.
+
+First build and activate the env before installing this package:
+
+    $ make build-env
+    $ conda activate comb_utils_py3.12
+
+Note, if you don't have Python installed, you need to pass the package name directly when you build the env: `make build-env PACKAGE_NAME=comb_utils`. If you have Python installed (e.g., this conda env already activated), then you don't need to because it uses Python to grab the package name from the `setup.cfg` file.
+
+Then, install this package and its dev dependencies:
+
+    $ make install
+
+This installs all the dependencies in your conda env site-packages, but the files for this package's installation are now your source files in this repo.
+
+### QC and testing
+
+Before pushing commits, you'll usually want to rebuild the env and run all the QC and testing:
+
+    $ make clean format full
+
+When making smaller commits, you might just want to run some of the smaller commands:
+
+    $ make clean format full-qc full-test
+
+As a final step, it's good practice to test run the workflow before opening a PR or pushing to an open PR. We don't want to waste GitHub runtime on a glitch that we could have caught before. You can use a make target for that:
+
+  $ make run-act
+
+That will run `.github/workflows/CI_CD.yml`. But, you can also run any workflow you'd like by using `act` directly. See https://nektosact.com.
+
+To use this tool, you'll need to have Docker installed and running on your machine: https://www.docker.com/. You'll also need to install `act` in your terminal:
+
+  $ brew install act

comb_utils-0.0.2.dist-info/RECORD

@@ -0,0 +1,11 @@
+comb_utils/__init__.py,sha256=He_mrvOz82NvEXxin1KsDQFqEFehEsWbHRzGAH7JMNE,229
+comb_utils/api/__init__.py,sha256=VskpwBKQUkO7pLLZrWvJngWwPVx72vx0xPSCfxKAr3g,41
+comb_utils/api/internal.py,sha256=-N9lH06EjHSoPkeQ_Tz_a2XzqJ3PYyAhhXa93glzutE,906
+comb_utils/api/public.py,sha256=Y0BsLAX8df-B4W87lcFuctNH8wtALQwcWxvHy6WzI-A,621
+comb_utils/lib/__init__.py,sha256=c-kh18Hkn-n2YGFLrJTxjv38h5KH9WmV1x4M5OBjKPY,16
+comb_utils/lib/example.py,sha256=qq3ZfrY1BEByapTjrEng0xkqXN7y9kpkAqgcLQn33uM,524
+comb_utils-0.0.2.dist-info/LICENSE,sha256=RbOwAEE8wb02qCx9uWRXbBUb0oAtrdZFvZFO9jARIdg,1070
+comb_utils-0.0.2.dist-info/METADATA,sha256=6g0WTZnmXkdSFBct-2q3x38sf_UjPTWRohAfnFyrvzs,6136
+comb_utils-0.0.2.dist-info/WHEEL,sha256=In9FTNxeP60KnTkGw7wk6mJPYd_dQSjEZmXdBdMCI-8,91
+comb_utils-0.0.2.dist-info/top_level.txt,sha256=bHRllaHFjJ1buzSdn8p1-7PeCC-QrCMCvhyapa7ND_k,11
+comb_utils-0.0.2.dist-info/RECORD,,

comb_utils-0.0.2.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (75.8.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

comb_utils-0.0.2.dist-info/top_level.txt

@@ -0,0 +1 @@
+comb_utils