runguard 0.3.0

Make Python functions safe to run more than once

runguard

Make Python functions safe to run more than once.

runguard ensures a function only executes once within a given time window (e.g. once per day, per hour, or per input) — even across multiple processes.

---

Why?

In real systems, the same function can get called multiple times:

• retries
• cron jobs
• API triggers
• AI-generated scripts
• accidental double execution

This can lead to:

• duplicate DB writes
• repeated API calls
• inconsistent state

runguard prevents that with a simple decorator.

---

Install

pip install runguard  # (or drop the file into your project)

---

Quick Example

from runguard import guard

@guard(schedule="daily")
def generate_report(user_id):
    print("Running expensive job...")
    return {"user": user_id}

generate_report(1)
generate_report(1)  # skipped
generate_report(2)  # runs (different input)

---

Features

• Runs once per time window (daily, hourly, weekly, or custom TTL)
• Parameter-aware (per input)
• Cross-process safe (file locking, works on Windows & Unix)
• Returns cached result
• Zero infrastructure required

---

Schedules

Daily / Hourly / Weekly

@guard(schedule="daily")
@guard(schedule="hourly")
@guard(schedule="weekly")

---

Custom TTL

@guard(ttl_seconds=600)  # once every 10 minutes

Cache Invalidation

from runguard import guard, invalidate_cache

@guard(schedule="daily")
def generate_report(user_id):
    return {"user": user_id}

# remove one cached call signature
invalidate_cache(fn=generate_report, args=(1,))

# remove all cached entries
invalidate_cache()

Command Line Invalidation

# remove all entries from default state file
python -m runguard invalidate

# remove all entries from a custom state file
python -m runguard invalidate --state-path /var/tmp/myapp/runguard-state.json

# remove one specific cached call signature
python -m runguard invalidate \
    --module myapp.jobs \
    --function generate_report \
    --args '[1]' \
    --kwargs '{}' \
    --state-path /var/tmp/myapp/runguard-state.json

---

Intended Usage

• scripts that may be triggered multiple times
• cron jobs / schedulers
• API endpoints with side effects
• anything that “should not run twice”

---

Future Improvements

• SQLite / Redis backend
• async support
• "run but don’t cache result" mode

---

Notes

runguard is not a framework.

It’s a small, reliable utility to make unsafe execution safe by default.