wardy-utils 0.4.1__tar.gz

wardy_utils-0.4.1/PKG-INFO

@@ -0,0 +1,167 @@
+Metadata-Version: 2.4
+Name: wardy-utils
+Version: 0.4.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: pydantic-settings>=2.12.0
+Requires-Dist: loguru>=0.7.3 ; extra == 'log'
+Requires-Dist: hishel[httpx]>=1.1.8 ; extra == 'web'
+Requires-Dist: httpx[brotli,http2,zstd]>=0.28.1 ; extra == 'web'
+Requires-Python: >=3.13
+Provides-Extra: log
+Provides-Extra: web
+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.
+
+## Installation
+
+```bash
+pip install wardy-utils
+```
+
+The base package only includes `pydantic-settings`. Install extras for additional functionality:
+
+```bash
+# Logging with Loguru
+pip install wardy-utils[log]
+
+# HTTP client with caching
+pip install wardy-utils[web]
+
+# Both
+pip install wardy-utils[log,web]
+```
+
+## Features
+
+### Logging (`wardy-utils[log]`)
+
+Flexible logging setup using [Loguru](https://github.com/Delgan/loguru), with optional [Logfire](https://logfire.pydantic.dev/) integration for cloud logging and metrics.
+
+**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
+- Automatic instrumentation of available libraries (system-metrics, psycopg, httpx, sqlalchemy, redis, asyncpg)
+
+**Basic usage:**
+
+```python
+from wardy_utils.log import configure_logging, logger
+
+# Set up logging to both stderr and a rotating file
+configure_logging("myapp")
+
+logger.info("Hello from Loguru!")
+
+# Standard logging is also intercepted:
+import logging
+logging.warning("This will also go to Loguru!")
+```
+
+**With Logfire cloud logging:**
+
+```python
+from wardy_utils.log import configure_logging, logger
+
+# service_name is required when using Logfire
+configure_logging("myapp", service_name="my-service")
+
+logger.info("This goes to Logfire too!")
+```
+
+Set `WARDY_UTILS_LOG_LOGFIRE_TOKEN` to enable Logfire. You must have `logfire` installed separately:
+
+```bash
+pip install logfire[system-metrics,psycopg,httpx]  # with desired extras
+```
+
+**Customization:**
+
+```python
+configure_logging(
+    "myapp",
+    service_name="my-service",  # Required for Logfire
+    standard_format="[{time}] {level} - {message}",
+    detail_format="{time} {file}:{line} {level} {message}",
+    log_rotation="1 day",
+    log_retention="7 days",
+)
+```
+
+**Environment variables:**
+
+| Variable | Description | Default |
+| -------- | ----------- | ------- |
+| `WARDY_UTILS_LOG_LOGFIRE_TOKEN` | Token for Logfire cloud logging | (disabled) |
+
+### HTTP Client (`wardy-utils[web]`)
+
+A high-level HTTP client built on [httpx](https://www.python-httpx.org/) and [hishel](https://hishel.com/) with built-in caching.
+
+**Basic usage:**
+
+```python
+from wardy_utils.web import cached_client
+
+client = cached_client()
+response = client.get("https://example.com")
+print(response.text)
+```
+
+**Pre-configured singletons:**
+
+```python
+from wardy_utils.web import sync_client, async_client
+
+# Sync client with default settings
+response = sync_client.get("https://example.com")
+
+# Or use async
+async def fetch():
+    response = await async_client.get("https://example.com")
+```
+
+Available singletons:
+- `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 variables:**
+
+| Variable | Description | Default |
+| -------- | ----------- | ------- |
+| `WARDY_UTILS_WEB_CACHE_DIR` | Directory for the sqlite cache file | In-memory |
+| `WARDY_UTILS_WEB_CACHE_FILENAME` | Filename for the sqlite cache file | `wardy_cache.db` |
+| `WARDY_UTILS_WEB_CACHE_TTL` | Cache TTL in seconds | `1800` (30 min) |
+| `WARDY_UTILS_WEB_TIMEOUT` | Request timeout in seconds | `45` |
+| `WARDY_UTILS_WEB_FORCE_CACHE` | If truthy, ignore origin cache-control headers | Disabled |
+| `WARDY_UTILS_WEB_HTTP2` | Enable or disable HTTP/2 | Enabled |
+
+**Proxy support:** The client inherits proxy settings from standard `http_proxy`, `https_proxy`, and `all_proxy` environment variables.
+
+## Requirements
+
+- Python 3.13 or higher
+
+## License
+
+This project is licensed under the MIT License.
+
+## Author
+
+Created by **Wardy**
+Email: [wardy3+gitlab@gmail.com](mailto:wardy3+gitlab@gmail.com)

wardy_utils-0.4.1/README.md

@@ -0,0 +1,144 @@
+# 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.
+
+## Installation
+
+```bash
+pip install wardy-utils
+```
+
+The base package only includes `pydantic-settings`. Install extras for additional functionality:
+
+```bash
+# Logging with Loguru
+pip install wardy-utils[log]
+
+# HTTP client with caching
+pip install wardy-utils[web]
+
+# Both
+pip install wardy-utils[log,web]
+```
+
+## Features
+
+### Logging (`wardy-utils[log]`)
+
+Flexible logging setup using [Loguru](https://github.com/Delgan/loguru), with optional [Logfire](https://logfire.pydantic.dev/) integration for cloud logging and metrics.
+
+**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
+- Automatic instrumentation of available libraries (system-metrics, psycopg, httpx, sqlalchemy, redis, asyncpg)
+
+**Basic usage:**
+
+```python
+from wardy_utils.log import configure_logging, logger
+
+# Set up logging to both stderr and a rotating file
+configure_logging("myapp")
+
+logger.info("Hello from Loguru!")
+
+# Standard logging is also intercepted:
+import logging
+logging.warning("This will also go to Loguru!")
+```
+
+**With Logfire cloud logging:**
+
+```python
+from wardy_utils.log import configure_logging, logger
+
+# service_name is required when using Logfire
+configure_logging("myapp", service_name="my-service")
+
+logger.info("This goes to Logfire too!")
+```
+
+Set `WARDY_UTILS_LOG_LOGFIRE_TOKEN` to enable Logfire. You must have `logfire` installed separately:
+
+```bash
+pip install logfire[system-metrics,psycopg,httpx]  # with desired extras
+```
+
+**Customization:**
+
+```python
+configure_logging(
+    "myapp",
+    service_name="my-service",  # Required for Logfire
+    standard_format="[{time}] {level} - {message}",
+    detail_format="{time} {file}:{line} {level} {message}",
+    log_rotation="1 day",
+    log_retention="7 days",
+)
+```
+
+**Environment variables:**
+
+| Variable | Description | Default |
+| -------- | ----------- | ------- |
+| `WARDY_UTILS_LOG_LOGFIRE_TOKEN` | Token for Logfire cloud logging | (disabled) |
+
+### HTTP Client (`wardy-utils[web]`)
+
+A high-level HTTP client built on [httpx](https://www.python-httpx.org/) and [hishel](https://hishel.com/) with built-in caching.
+
+**Basic usage:**
+
+```python
+from wardy_utils.web import cached_client
+
+client = cached_client()
+response = client.get("https://example.com")
+print(response.text)
+```
+
+**Pre-configured singletons:**
+
+```python
+from wardy_utils.web import sync_client, async_client
+
+# Sync client with default settings
+response = sync_client.get("https://example.com")
+
+# Or use async
+async def fetch():
+    response = await async_client.get("https://example.com")
+```
+
+Available singletons:
+- `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 variables:**
+
+| Variable | Description | Default |
+| -------- | ----------- | ------- |
+| `WARDY_UTILS_WEB_CACHE_DIR` | Directory for the sqlite cache file | In-memory |
+| `WARDY_UTILS_WEB_CACHE_FILENAME` | Filename for the sqlite cache file | `wardy_cache.db` |
+| `WARDY_UTILS_WEB_CACHE_TTL` | Cache TTL in seconds | `1800` (30 min) |
+| `WARDY_UTILS_WEB_TIMEOUT` | Request timeout in seconds | `45` |
+| `WARDY_UTILS_WEB_FORCE_CACHE` | If truthy, ignore origin cache-control headers | Disabled |
+| `WARDY_UTILS_WEB_HTTP2` | Enable or disable HTTP/2 | Enabled |
+
+**Proxy support:** The client inherits proxy settings from standard `http_proxy`, `https_proxy`, and `all_proxy` environment variables.
+
+## Requirements
+
+- Python 3.13 or higher
+
+## License
+
+This project is licensed under the MIT License.
+
+## Author
+
+Created by **Wardy**
+Email: [wardy3+gitlab@gmail.com](mailto:wardy3+gitlab@gmail.com)

wardy_utils-0.4.1/pyproject.toml

@@ -0,0 +1,45 @@
+[project]
+authors = [{ name = "Wardy", email = "wardy3+gitlab@gmail.com" }]
+description = "General Utilities"
+license = "MIT"
+name = "wardy-utils"
+readme = { file = "README.md", content-type = "text/markdown" }
+requires-python = ">=3.13"
+version = "0.4.1"
+
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+dependencies = ["pydantic-settings>=2.12.0"]
+
+[project.optional-dependencies]
+log = ["loguru>=0.7.3"]
+web = ["hishel[httpx]>=1.1.8", "httpx[brotli,http2,zstd]>=0.28.1"]
+
+[dependency-groups]
+dev = ["common-tools[dev]>=0.1.0"]
+test = ["common-tools[test]>=0.3.0"]
+
+[tool.uv.sources]
+common-tools = { path = "../common-tools" }
+
+[build-system]
+build-backend = "uv_build"
+requires = ["uv_build>=0.9.7,<0.10.0"]
+
+[tool.pytest.ini_options]
+addopts = "-v --capture=tee-sys --durations=3 -p no:pastebin -p no:nose -p no:doctest"
+asyncio_default_fixture_loop_scope = "function"
+log_level = "DEBUG"
+pythonpath = [".", "src", "tests"]
+xfail_strict = true
+
+[tool.coverage.report]
+exclude_lines = ["@.*overload", "pragma: no cover", 'class \w+\((typing.|tp.)?Protocol\)']

wardy_utils-0.4.1/src/wardy_utils/log.py

@@ -0,0 +1,176 @@
+"""Set up logging using the Loguru library.
+
+Requires the 'log' extra: pip install wardy-utils[log]
+"""
+
+from __future__ import annotations
+
+import inspect
+import logging
+import sys
+from pathlib import Path
+from typing import TYPE_CHECKING, Final
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+if TYPE_CHECKING:  # pragma: no cover
+    from collections.abc import Callable
+
+try:
+    from loguru import logger
+except ImportError as e:  # pragma: no cover
+    msg = "loguru is required for wardy_utils.log. Install with: pip install wardy-utils[log]"
+    raise ImportError(msg) from e
+
+try:
+    import logfire
+except ImportError:  # pragma: no cover
+    logfire = None
+
+
+# ----- Settings -----
+
+
+class LogSettings(BaseSettings):
+    """Environment-driven settings for logging."""
+
+    logfire_token: str = ""
+    logfire_service_name: str = ""
+    logfire_env_prefix: str = ""
+
+    model_config = SettingsConfigDict(env_prefix="WARDY_UTILS_LOG_", case_sensitive=False)
+
+
+# ----- Constants -----
+
+STANDARD: Final = "[{time:HH:mm:ss}] {level} - {message}"
+DETAIL: Final = "{time} {file:>25}:{line:<4} {level:<8} {message}"
+
+# ----- Public API -----
+
+__all__ = [
+    "DETAIL",
+    "STANDARD",
+    "LogSettings",
+    "configure_logfire",
+    "configure_logging",
+    "logger",
+]
+
+
+def configure_logging(
+    log_filename: str | Path,
+    *,
+    service_name: str | None = None,
+    standard_format: str = STANDARD,
+    detail_format: str = DETAIL,
+    log_rotation: str = "1 hour",
+    log_retention: str = "7 days",
+) -> None:
+    """Setup Loguru logging for the application.
+
+    Args:
+        log_filename: Base name for the log file (will have .log suffix added).
+        service_name: Service name for Logfire cloud logging. Required if using Logfire.
+        standard_format: Format for stderr output.
+        detail_format: Format for file and Logfire output.
+        log_rotation: When to rotate log files.
+        log_retention: How long to keep old log files.
+
+    Environment variables (prefix WARDY_UTILS_LOG_):
+        LOGFIRE_TOKEN: Token for Logfire cloud logging.
+    """
+    settings = LogSettings()
+
+    # Capture things like Hishel logging
+    intercept_logging()
+
+    # Replace the default StdErr handler.
+    logger.remove()
+    logger.add(sys.stderr, level="WARNING", format=standard_format)
+
+    # Add a rotating file handler.
+    log_filename = Path(log_filename).with_suffix(".log")
+    logger.add(
+        log_filename,
+        level="DEBUG",
+        format=detail_format,
+        rotation=log_rotation,
+        retention=log_retention,
+    )
+
+    # Set up Logfire if token is configured
+    if settings.logfire_token:
+        configure_logfire(settings.logfire_token, service_name, detail_format)
+
+
+def configure_logfire(token: str, service_name: str | None, log_format: str) -> None:
+    """Configure Logfire cloud logging with available instrumentations.
+
+    Args:
+        token: Logfire API token.
+        service_name: Service name for Logfire. Required.
+        log_format: Log format string for Logfire handler.
+
+    Raises:
+        ImportError: If logfire is not installed.
+        ValueError: If service_name is not provided.
+    """
+    if logfire is None:
+        msg = "logfire is required for cloud logging. Install with: pip install logfire"
+        raise ImportError(msg)
+
+    if not service_name:
+        msg = "service_name is required for Logfire"
+        raise ValueError(msg)
+
+    logfire.configure(token=token, service_name=service_name)
+    logger.add(logfire.loguru_handler()["sink"], level="TRACE", format=log_format)
+
+    # Instrument available integrations
+    _try_instrument("system_metrics", logfire.instrument_system_metrics)
+    _try_instrument("psycopg", logfire.instrument_psycopg)
+    _try_instrument("httpx", logfire.instrument_httpx)
+    _try_instrument("sqlalchemy", logfire.instrument_sqlalchemy)
+    _try_instrument("redis", logfire.instrument_redis)
+    _try_instrument("asyncpg", logfire.instrument_asyncpg)
+
+
+def _try_instrument(name: str, func: Callable[[], None]) -> None:
+    """Try to instrument a library, logging the result."""
+    try:
+        func()
+    except RuntimeError:
+        logger.debug(f"Logfire: {name} not available")
+    else:
+        logger.debug(f"Logfire: instrumented {name}")
+
+
+# ----- Interface to the standard logging module -----
+
+
+class InterceptHandler(logging.Handler):
+    """Send logs to Loguru."""
+
+    def emit(self, record: logging.LogRecord) -> None:
+        """Emit a log record."""
+        # Get corresponding Loguru level if it exists.
+        level: str | int
+        try:
+            level = logger.level(record.levelname).name
+        except ValueError:  # pragma: no cover
+            level = record.levelno
+
+        # Find caller from where originated the logged message.
+        frame, depth = inspect.currentframe(), 0
+        while frame and (depth == 0 or frame.f_code.co_filename == logging.__file__):
+            frame = frame.f_back
+            depth += 1
+
+        logger.opt(depth=depth, exception=record.exc_info).log(level, record.getMessage())
+
+
+def intercept_logging() -> None:
+    """Intercept standard logging and send it to Loguru."""
+    # Configure the root logger
+    logging.basicConfig(handlers=[InterceptHandler()], level=0, force=True)

wardy_utils-0.4.1/src/wardy_utils/web.py

@@ -0,0 +1,195 @@
+"""General internet helpers.
+
+Requires the 'web' extra: pip install wardy-utils[web]
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+from dataclasses import dataclass
+from datetime import timedelta
+from pathlib import Path
+from typing import Final, Literal, overload
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+try:
+    from hishel import AsyncSqliteStorage, FilterPolicy, SyncSqliteStorage
+    from hishel.httpx import AsyncCacheClient, SyncCacheClient
+except ImportError as e:  # pragma: no cover
+    msg = "hishel/httpx required for wardy_utils.web. Install: pip install wardy-utils[web]"
+    raise ImportError(msg) from e
+
+logging.getLogger("httpcore").setLevel(logging.INFO)
+# hishel INFO level is appropriate - DEBUG is verbose about cached responses
+logging.getLogger("hishel").setLevel(logging.INFO)
+
+# ----- Constants -----
+
+CACHE_TTL_DEFAULT_SECONDS: Final = timedelta(minutes=30).total_seconds()
+HTTP_TIMEOUT_SECONDS: Final = timedelta(seconds=45).total_seconds()
+
+
+class WebSettings(BaseSettings):
+    """Environment-driven defaults for HTTP clients."""
+
+    cache_dir: str | Path = ""
+    cache_filename: str = "wardy_cache.db"
+    cache_ttl: float = CACHE_TTL_DEFAULT_SECONDS
+    timeout: float = HTTP_TIMEOUT_SECONDS
+    force_cache: bool = False
+    http2: bool = True
+
+    model_config = SettingsConfigDict(env_prefix="WARDY_UTILS_WEB_", case_sensitive=False)
+
+
+@dataclass(frozen=True)
+class ClientConfig:
+    """Configuration for a cached HTTP client."""
+
+    sync: bool
+    force: bool
+    cache_db: str
+    ttl: float
+    timeout: float
+    http2: bool
+
+
+_CLIENTS: dict[ClientConfig, SyncCacheClient | AsyncCacheClient] = {}
+_CLIENTS_LOCK = threading.Lock()
+
+
+def _resolve_config(
+    *,
+    sync: bool,
+    force: bool | None,
+    cache_dir: str | None,
+    ttl: float | None,
+    timeout: float | None,
+    http2: bool | None,
+) -> ClientConfig:
+    env = WebSettings()
+
+    resolved_ttl = ttl if ttl is not None else env.cache_ttl
+    resolved_timeout = timeout if timeout is not None else env.timeout
+    resolved_force = force if force is not None else env.force_cache
+    resolved_http2 = http2 if http2 is not None else env.http2
+
+    resolved_cache_dir = cache_dir if cache_dir is not None else env.cache_dir
+
+    if resolved_cache_dir:
+        cache_path = Path(resolved_cache_dir)
+        cache_path.mkdir(parents=True, exist_ok=True)
+        cache_db = str(cache_path / env.cache_filename)
+    else:
+        cache_db = ":memory:"
+
+    return ClientConfig(
+        sync=sync,
+        force=resolved_force,
+        cache_db=cache_db,
+        ttl=resolved_ttl,
+        timeout=resolved_timeout,
+        http2=resolved_http2,
+    )
+
+
+def _build_client(config: ClientConfig) -> SyncCacheClient | AsyncCacheClient:
+    storage: SyncSqliteStorage | AsyncSqliteStorage
+    if config.cache_db != ":memory:":
+        Path(config.cache_db).touch(exist_ok=True)
+
+    if config.sync:
+        storage = SyncSqliteStorage(database_path=config.cache_db, default_ttl=config.ttl)
+    else:
+        storage = AsyncSqliteStorage(database_path=config.cache_db, default_ttl=config.ttl)
+
+    policy = FilterPolicy() if config.force else None
+    client_class = SyncCacheClient if config.sync else AsyncCacheClient
+
+    return client_class(
+        follow_redirects=True,
+        storage=storage,
+        policy=policy,
+        timeout=config.timeout,
+        http2=config.http2,
+    )
+
+
+# ----- Handle httpx client and hishel caching -----
+
+
+@overload
+def cached_client() -> SyncCacheClient: ...
+@overload
+def cached_client(
+    *,
+    sync: Literal[True],
+    force: bool | None = ...,
+    ttl: float | None = ...,
+    timeout: float | None = ...,
+    cache_dir: str | None = ...,
+    http2: bool | None = ...,
+) -> SyncCacheClient: ...
+@overload
+def cached_client(
+    *,
+    sync: Literal[False],
+    force: bool | None = ...,
+    ttl: float | None = ...,
+    timeout: float | None = ...,
+    cache_dir: str | None = ...,
+    http2: bool | None = ...,
+) -> AsyncCacheClient: ...
+
+
+def cached_client(
+    *,
+    sync: bool = True,
+    force: bool | None = None,
+    ttl: float | None = None,
+    timeout: float | None = None,
+    cache_dir: str | None = None,
+    http2: bool | None = None,
+) -> SyncCacheClient | AsyncCacheClient:
+    """Return a cached HTTPX client (sync or async).
+
+    By default, uses in-memory cache (safe for production/FastAPI).
+    In test environments, set WARDY_UTILS_CACHE_DIR to enable
+    persistent filesystem cache across test runs.
+
+    Args:
+        sync (bool): Whether to use sync or async client. Defaults to True.
+        force (bool | None): Whether to force cache regardless of origin headers.
+                     Uses FilterPolicy which ignores cache-control directives.
+                     Defaults to env WARDY_UTILS_FORCE_CACHE or False.
+        ttl (float | None): Time to live for cache entries in seconds.
+                     Defaults to env WARDY_UTILS_CACHE_TTL or 30 minutes.
+        timeout (float | None): Timeout for requests in seconds.
+                     Defaults to env WARDY_UTILS_TIMEOUT or 45 seconds.
+        cache_dir (str | None): Directory to use for persistent cache. If not set,
+                     uses env WARDY_UTILS_CACHE_DIR or in-memory cache.
+        http2 (bool | None): Toggle HTTP/2 support. Defaults to env WARDY_UTILS_HTTP2 or True.
+
+    Returns:
+        SyncCacheClient | AsyncCacheClient: A cached HTTPX client.
+    """
+    config = _resolve_config(
+        sync=sync, force=force, cache_dir=cache_dir, ttl=ttl, timeout=timeout, http2=http2
+    )
+
+    with _CLIENTS_LOCK:
+        client = _CLIENTS.get(config)
+
+        if client is None or getattr(client, "is_closed", False):
+            client = _build_client(config)
+            _CLIENTS[config] = client
+
+    return client
+
+
+sync_client = cached_client(sync=True)
+sync_force_client = cached_client(sync=True, force=True)
+async_client = cached_client(sync=False)
+async_force_client = cached_client(sync=False, force=True)