wdecorators

wdecorators is a high-level Python decorator library providing a collection of ready-to-use decorators for performance profiling, resilience (retry, timeout, rate-limiting), debugging, input sanitization, structured logging with Graylog, caching, and periodic task scheduling.

Installation

pip install wdecorators

Optional extras

# For the periodic task scheduler dashboard (FastAPI + Uvicorn + JWT)
pip install wdecorators[scheduler]

# For the Graylog FastAPI middleware
pip install wdecorators[graylog]

Quick Start

from wdecorators import benchmark, retry, time_execution, singleton

@benchmark
def my_function():
    return sum(range(1000))

@retry(times=3)
def unreliable_function():
    import random
    if random.random() < 0.5:
        raise ConnectionError("Network issue")
    return "OK"

@singleton
class Database:
    def __init__(self):
        print("Connecting to database...")

print(my_function())
print(unreliable_function())
db1 = Database()
db2 = Database()
print(db1 is db2)  # True

Decorator Reference

Performance

Resilience

Debugging

Security

Utilities

Graylog Logging

Periodic Task Scheduler

Examples

Check the examples/ directory for runnable code covering every decorator:

# Run any example
python examples/performance/benchmark_example.py
python examples/resilience/retry_example.py
python examples/periodic_task/full_featured.py
# ... and many more organized by category

Periodic Tasks

from wdecorators import Periodic_task_sched
import asyncio

controller = Periodic_task_sched(auto_database=True, handle_signals=True, max_workers=5)

@controller.periodic_execution(cron="*/1 * * * *", allow_concurrent=False, enable_api=True)
async def async_cron_task():
    print("Async cron task running...")
    await asyncio.sleep(1)

@controller.periodic_execution(run_at=["04:00", "12:00", "20:00"])
def daily_reports():
    print("Daily report task running...")

async_cron_task()
daily_reports()
controller.start_api()

controller.run_forever()

Graylog Structured Logging

from wdecorators import init_logger, log_exceptions, logger

init_logger("my_app", graylog_host="192.168.1.100")

@log_exceptions(context={"send_to_graylog": True})
def process_order(order_id: int):
    logger.bind(send_to_graylog=True).info(f"Processing order {order_id}")
    # ... business logic

Project Structure

wdecorators/
├── wdecorators/
│   ├── __init__.py           # Public API exports
│   ├── general/              # General-purpose decorators
│   ├── graylog/              # Graylog GELF logging integration
│   ├── log_calls/            # Simple call logging decorator
│   └── periodic_scheduller/  # Periodic task scheduler with dashboard & metrics
│       ├── __init__.py
│       └── controller.py
├── examples/                 # Categorized runnable examples
│   ├── debugging/            # Debugging and tracing examples
│   ├── graylog/              # Graylog integration examples
│   ├── performance/          # Benchmarking and caching examples
│   ├── periodic_task/        # Periodic task scheduler examples (basic, advance, daily_schedule, full_featured)
│   ├── resilience/           # Retry, timeout, rate-limiting examples
│   ├── security/             # Input sanitization and authentication examples
│   ├── utilities/            # Singleton, JSON, run_once examples
│   └── validation/           # Runtime type & length validation examples
├── pyproject.toml
└── README.md

Key Technologies

• Python 3.8+: Core runtime.
• FastAPI & Uvicorn: Web dashboard and server for monitoring periodic task schedulers.
• PyJWT & Jinja2: Authentication and templating for scheduler dashboard.
• Loguru: Advanced logging engine with Graylog GELF support.
• SQLite / PostgreSQL: Database backends for task logging and execution history.
• Pytest & Coverage: Unit testing framework and test coverage reporting.

Development

git clone https://github.com/wisrovi/wdecorators.git
cd wdecorators
pip install -e ".[scheduler]"

Code quality

pip install isort black
isort .
black .

License

MIT © William Steve Rodriguez Villamizar