Metadata-Version: 2.4
Name: wardy-utils
Version: 0.3.1
Summary: General Utilities
Author: Wardy
Author-email: Wardy <wardy3+gitlab@gmail.com>
License-Expression: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: hishel[httpx]>=1.1.4
Requires-Dist: httpx[http2]>=0.28.1
Requires-Dist: pydantic-settings>=2.12.0
Requires-Dist: logfire[httpx]>=3.16.1 ; extra == 'logfire'
Requires-Dist: loguru>=0.7.3 ; extra == 'loguru'
Requires-Python: >=3.13
Provides-Extra: logfire
Provides-Extra: loguru
Description-Content-Type: text/markdown

# Wardy Utils

**Wardy Utils** is a collection of general-purpose utilities designed to simplify and enhance your Python scripting experience. This library provides reusable components that can be integrated into your projects to save time and effort.

## Features


### Logging Utilities

- **`log`**: Flexible logging setup using Loguru, with optional Logfire integration for cloud logging and metrics. Includes helpers to intercept standard logging and route it through Loguru for unified log handling.

### HTTP Utilities

- **`http`**: A high-level HTTP client built on top of `httpx` and `hishel`, setting some caching and timeout comment settings.

## Installation


To install Wardy Utils, use pip:

```bash
pip install wardy-utils
```

#### Logging extras

To use logging features, install with the appropriate extras:

- For Loguru logging:
	```bash
	pip install wardy-utils[loguru]
	```
- For Logfire integration:
	```bash
	pip install wardy-utils[logfire]
	```

## Usage

### Logging Example

`wardy_utils.log` provides flexible logging setup using [Loguru](https://github.com/Delgan/loguru), with optional [Logfire](https://logfire.dev/) integration for cloud logging and metrics. It can intercept standard Python logging and route it through Loguru for unified log handling.

**Key features:**
- Simple setup for rotating file and stderr logging
- Intercepts standard Python logging and redirects to Loguru
- Optional Logfire integration for cloud log aggregation and system metrics
- Customizable log formats, rotation, and retention

**Basic usage:**

```python
from wardy_utils.log import configure_logging

# Set up logging to both stderr and a rotating file
configure_logging("myapp")

from loguru import logger
logger.info("Hello from Loguru!")

# Standard logging is also intercepted:
import logging
logging.warning("This will also go to Loguru!")
```

#### Logfire Integration

If the environment variable `LOGFIRE_TOKEN` is set, Logfire will be configured automatically for cloud log aggregation and system metrics. You can also set `REFLEX_ENV_MODE` to prefix the service name.

#### Customization

You can customize log formats, rotation, and retention:

```python
configure_logging(
	"myapp",
	standard_format="[{time}] {level} - {message}",
	detail_format="{time} {file}:{line} {level} {message}",
	log_rotation="1 day",
	log_retention="7 days",
)
```


### HTTP Client Example

```python
from wardy_utils.web import cached_client

client = cached_client()
response = client.get("https://example.com")
print(response.text)
```

Convenience singletons live in `wardy_utils.web` if you want ready-made instances without wiring:

- `sync_client`: default sync client.
- `sync_force_client`: sync client that ignores origin cache headers.
- `async_client`: default async client.
- `async_force_client`: async client that ignores origin cache headers.

Environment overrides for the HTTP client:

| Variable                     | Description                                                       | Default                    |
| ---------------------------- | ----------------------------------------------------------------- | -------------------------- |
| `WARDY_UTILS_CACHE_DIR`      | Directory for the sqlite cache file.                              | In-memory                  |
| `WARDY_UTILS_CACHE_FILENAME` | Filename for the sqlite cache file when a cache directory is set. | `wardy-utils-cache.sqlite` |
| `WARDY_UTILS_CACHE_TTL`      | Cache TTL in seconds.                                             | `1800`                     |
| `WARDY_UTILS_TIMEOUT`        | Request timeout in seconds.                                       | `45`                       |
| `WARDY_UTILS_FORCE_CACHE`    | If truthy, ignore origin cache-control headers.                   | Disabled                   |
| `WARDY_UTILS_HTTP2`          | Enable or disable HTTP/2.                                         | Enabled                    |

Proxy behaviour: the client inherits proxy settings from standard `http_proxy`, `https_proxy`, and `all_proxy` environment variables, so you can point traffic via your organisation's proxy without code changes.

## Requirements

- Python 3.13.3 or higher

## Contributing

Contributions are welcome! Run the test suite with coverage via:

```bash
pytest --cov=src --cov-report=xml
```

Feel free to open issues or submit pull requests to improve the library.

## License

This project is licensed under the MIT License.

## Author

Created by **Wardy**  
Email: [wardy3+gitlab@gmail.com](mailto:wardy3+gitlab@gmail.com)
