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

pip install wardy-utils

The base package only includes pydantic-settings. Install extras for additional functionality:

# Logging with Loguru
pip install wardy-utils[log]

# HTTP client with caching
pip install wardy-utils[web]

# Neon free-plan usage check
pip install wardy-utils[neon]

# Both
pip install wardy-utils[log,web]

Features

Logging (wardy-utils[log])

Flexible logging setup using Loguru, with optional Logfire 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:

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:

from wardy_utils.log import configure_logging, logger

# service_name defaults to the current working directory name
configure_logging("my-app")

# Or specify explicitly
configure_logging("my-app", service_name="my-app", environment="prod")

logger.info("This goes to Logfire too!")

Set WARDY_UTILS_LOG_LOGFIRE_TOKEN to enable Logfire. You must have logfire installed separately:

pip install logfire[system-metrics,psycopg,httpx]  # with desired extras

Customization:

from wardy_utils.log import configure_logging, LogConfig

config = LogConfig(
    file_level="INFO",
    standard_format="[{time}] {level} - {message}",
    detail_format="{time} {file}:{line} {level} {message}",
    rotation="1 hour",
    retention="14 days",
)

configure_logging("my-app", service_name="my-app", config=config)

Environment variables:

Cascade behavior when not explicitly set:

• LOGFIRE_SERVICE_NAME: Falls back to the current working directory name (e.g. beer-cloud)
• LOGFIRE_ENVIRONMENT: Falls back to APP_ENVIRONMENT → REFLEX_ENV_MODE → NODE_ENV → ENVIRONMENT

HTTP Client (wardy-utils[web])

A high-level HTTP client built on httpx and hishel with built-in caching.

Basic usage:

from wardy_utils.web import cached_client

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

Pre-configured singletons:

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:

Proxy support: The client inherits proxy settings from standard http_proxy, https_proxy, and all_proxy environment variables.

Neon usage (wardy-utils[neon])

Checks a Neon project's compute usage against the free plan's monthly CU-hour allowance, and projects the month-end total from the rate since the 1st. Calling Neon's API does not wake the database. Nothing is logged; HTTP and parsing errors (httpx.HTTPError, KeyError, ValueError) propagate for the caller to handle.

from wardy_utils.neon import get_usage

usage = await get_usage("my-project-id", api_key, allowance=100)
print(usage.cu_hours, usage.pct_used, usage.projected_cu_hours, usage.projected_pct)

With several worker processes, claim_usage_lock(path) lets only one of them call Neon: it returns an open lock file while held, or None if another process has it.

Requirements

• Python 3.12 or higher
• Linux or macOS (wardy_utils.neon uses fcntl for its usage lock)

License

This project is licensed under the MIT License.

Author

Created by Wardy Email: wardy3+gitlab@gmail.com