Metadata-Version: 2.1
Name: red_utils
Version: 0.2.16
Summary: Collection of utility scripts/functions that I use frequently.
Author-email: redjax <none@none.com>, redjax <jackenyon@gmail.com>
License: MIT
Project-URL: Repository, https://github.com/redjax/red-utils
Project-URL: Documentation, https://red-utils.readthedocs.io/en/latest/
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: diskcache>=5.6.3
Requires-Dist: loguru>=0.7.2
Requires-Dist: msgpack>=1.0.7
Requires-Dist: httpx>=0.26.0
Requires-Dist: pendulum>=3.0.0
Requires-Dist: rich>=13.7.0
Provides-Extra: standard
Requires-Dist: diskcache>=5.6.3; extra == "standard"
Requires-Dist: loguru>=0.7.2; extra == "standard"
Requires-Dist: httpx>=0.26.0; extra == "standard"
Requires-Dist: pendulum>=3.0.0; extra == "standard"
Requires-Dist: rich>=13.7.0; extra == "standard"
Requires-Dist: msgpack>=1.0.7; extra == "standard"
Requires-Dist: sqlalchemy>=2.0.25; extra == "standard"
Provides-Extra: all
Requires-Dist: diskcache>=5.6.3; extra == "all"
Requires-Dist: fastapi>=0.109.0; extra == "all"
Requires-Dist: uvicorn[standard]>=0.25.0; extra == "all"
Requires-Dist: loguru>=0.7.2; extra == "all"
Requires-Dist: httpx>=0.26.0; extra == "all"
Requires-Dist: msgpack>=1.0.7; extra == "all"
Requires-Dist: pendulum>=3.0.0; extra == "all"
Requires-Dist: sqlalchemy>=2.0.25; extra == "all"
Requires-Dist: arrow>=1.3.0; extra == "all"
Requires-Dist: pandas>=2.1.4; extra == "all"
Requires-Dist: fastparquet>=2023.10.1; extra == "all"
Provides-Extra: fastapi
Requires-Dist: fastapi>=0.109.0; extra == "fastapi"
Requires-Dist: sqlalchemy>=2.0.25; extra == "fastapi"
Requires-Dist: loguru>=0.7.2; extra == "fastapi"
Requires-Dist: httpx>=0.26.0; extra == "fastapi"
Requires-Dist: msgpack>=1.0.7; extra == "fastapi"
Requires-Dist: uvicorn>=0.25.0; extra == "fastapi"
Requires-Dist: pendulum>=3.0.0; extra == "fastapi"
Provides-Extra: http
Requires-Dist: httpx>=0.26.0; extra == "http"
Requires-Dist: diskcache>=5.6.3; extra == "http"
Requires-Dist: loguru>=0.7.2; extra == "http"
Requires-Dist: pendulum>=3.0.0; extra == "http"
Requires-Dist: msgpack>=1.0.7; extra == "http"
Requires-Dist: pendulum>=2.1.2; extra == "http"
Provides-Extra: arrow
Requires-Dist: arrow>=1.3.0; extra == "arrow"
Provides-Extra: data
Requires-Dist: ipykernel>=6.28.0; extra == "data"
Requires-Dist: pandas>=2.1.4; extra == "data"
Requires-Dist: fastparquet>=2023.10.1; extra == "data"
Provides-Extra: dataframes
Requires-Dist: pandas>=2.1.4; extra == "dataframes"
Requires-Dist: fastparquet>=2023.10.1; extra == "dataframes"
Provides-Extra: ci
Requires-Dist: tox>=4.12.0; extra == "ci"
Requires-Dist: ruff>=0.1.13; extra == "ci"
Requires-Dist: black>=23.12.1; extra == "ci"
Requires-Dist: pytest>=7.4.4; extra == "ci"
Provides-Extra: docs
Requires-Dist: pygments>=2.17.2; extra == "docs"
Requires-Dist: mkdocs>=1.5.3; extra == "docs"
Requires-Dist: mkdocs-material>=9.5.4; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.24.0; extra == "docs"
Requires-Dist: markdown-include>=0.8.1; extra == "docs"
Requires-Dist: mkdocs-gen-files>=0.5.0; extra == "docs"
Requires-Dist: mkdocs-autorefs>=0.5.0; extra == "docs"
Requires-Dist: mkdocs-section-index>=0.3.8; extra == "docs"
Requires-Dist: mkdocs-literate-nav>=0.6.1; extra == "docs"

# red-utils

⚠️**Important**⚠️: This is my first Python package. I'm experimenting with CI/CD and Pypi. This library is most likely not useful to anyone else, may be broken at times, may undergo refactors with little to no notice/documentation, and all that other awful stuff that comes with being an amateur developer doing this in their free time 🙃

# Table of Contents

- [red-utils](#red-utils)
- [Table of Contents](#table-of-contents)
- [Description](#description)
  - [Dynamic imports](#dynamic-imports)
- [Installation](#installation)
  - [Dependency groups:](#dependency-groups)
    - [Dependency install group examples](#dependency-install-group-examples)
- [Modules](#modules)
- [Developing red-utils](#developing-red-utils)

# Description

- 🔗 [Project Home - Github Repository](https://github.com/redjax/red-utils)
- 🐍 [Red Utils on Pypi](https://pypi.org/project/red_utils/)
- 📖 [Red Utils Docs](https://red-utils.readthedocs.io/en/latest/)


A collection of utility scripts/functions that I use frequently. Includes helper functions/default variables for libraries like `loguru`, `diskcache`, and `msgpack`.

The utilities are broken down into 2 modules:

- `std`: Utilities with no external dependencies, only the Python `stdlib`.
- `ext`: Utilities for dependencies like `loguru` and `msgpack`
  - Note: It is generally a good practice to import `ext` modules as a whole, instead of importing functions/variables from the module.
  - This is because some of the function names I chose may be common (like `get_ts()` in the `ext.time_utils` module).
  - Example:
    ```
    from red_utils.ext import time_utils

    now = time_utils.get_ts()
    ```

    or, with `pendulum`:
    ```
    from red_utils.ext.time_utils import pendulum_utils

    now = pendulum_utils.get_ts()
    ```
     
Common code shared by the `std` and `ext` modules can be imported from `red_utils.core` and `red_utils.domain`. Any code in these modules should be clean of any external dependency. This is because the `std` module imports from `core`, and adding non-stdlib functionality in `red_utils.core` breaks the philosophy of the `stdlib` module. I may introduce a `red_utils.ext.core` at some point.

Some domain objects (`dataclass` or regular Python classes) may be stored in `red_utils.domain`. As of release `v0.2.12`, this module is empty, but future releases may bring some utilities in the form of a class.

Custom/common exceptions are stored in `red_utils.exc`.

## Dynamic imports

The `red-utils` package makes use of the Python stdlib `pkgutil` module to control imports. Packages in the `ext` module are only imported and available in `red_utils` if the corresponding dependency exists.

For instance, `red_utils.ext.msgpack_utils` will only be available if this check in [src/red_utils/ext/__init__.py](https://github.com/redjax/red-utils/blob/main/src/red_utils/ext/__init__.py) passes:
```
import pkgutil

...

if pkgutil.find_loader("msgpack"):
  from . import msgpack_utils
```

`pkgutil.find_loader()` is used throughout the app to control imports and ensure `red_utils` is stable, by keeping uninstalled module's utilities out of the namespace.

# Installation

This project uses dependencies groups, meaning it can be installed with `pip install red-utils` for the base package, or with dependency groups like `pip install red-utils[all]` (to install all packages with a corresponding red-util module), `pip install red-utils[http]` (to install some helpful packages for HTTP requests, i.e. `httpx` and `diskcache`), and more.

- pip
  - `pip install red-utils`
- pdm
  - `pdm add red-utils`

## Dependency groups:

*Note*: I will do my best to update this, but to get an accurate view of available dependency groups and the packages that will be installed, check the [`pyproject.toml`](./pyproject.toml) file. Look for the dependency lists, i.e. `dependencies = [` (the base set of dependencies), `all = [`, `http = [`, etc.

`[all]`: Install all packages that have a corresponding util. This may be a large install, and is generally not recommended.

`[arrow]`: By default, the `pendulum` library is used for `time_utils`. Installing `red_utils[arrow]` allows for importing `arrow` functions from `red_utils.ext.time_utils.arrow`.

`[fastapi]`: Dependencies for `fastapi_utils`

`[http]`: My standard "HTTP toolkit." Comes with a request client (`httpx`), logging (`loguru`), caching (`diskcache`), & more.

### Dependency install group examples

- pip:
  - `pip install red-utils[fastapi,http]`
- pdm:
  - `pdm add red-utils[fastapi,http]`

# Modules

Check the [Github page](https://github.com/redjax/red-utils/tree/main/src/red_utils) to see modules in the [`ext`](https://github.com/redjax/red-utils/tree/main/src/red_utils/ext) and [`std`](https://github.com/redjax/red-utils/tree/main/src/red_utils/std) modules (or click one of those words to be taken there).

# Developing red-utils

Please see the [developing docs](docs/developing.md) for instructions on setting up a dev environment to work on `red-utils`.
