pyscheduler-fox 1.0.0
A powerful yet simple Python task scheduler
License: MIT
Requires Python: >=3.7
Keywords: scheduler, task, cron, async, threading, automation, jobs, background, periodic, interval, daemon, service

# PyScheduler

**The simplest and most powerful Python scheduler**

[![PyPI version](https://badge.fury.io/py/pyscheduler.svg)](https://badge.fury.io/py/pyscheduler)
[![Python versions](https://img.shields.io/pypi/pyversions/pyscheduler.svg)](https://pypi.org/project/pyscheduler/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

PyScheduler revolutionizes task scheduling in Python. **3 lines are enough** to get started, yet it offers all the power needed for production.

## ✨ **Features**

- 🎯 **Ultra-simple**: Get started in 30 seconds
- ⚡ **High-performance**: Optimized threading, native async tasks
- 🛡️ **Robust**: Automatic retry, advanced error handling
- 📊 **Comprehensive**: Detailed logs, monitoring, statistics
- 🕐 **Flexible**: Intervals, CRON, one-off tasks
- 📄 **Production-ready**: YAML configuration, integrated CLI

## 🚀 **Installation**

```bash
pip install pyscheduler[full]
```

<details>
<summary>Minimal installation (without optional dependencies)</summary>

```bash
pip install pyscheduler
```
</details>

## ⚡ **Quick Start**

```python
from pyscheduler import PyScheduler, task

@task(60)  # Every minute
def backup_data():
    print("Automatic backup!")

@task(cron="0 9 * * 1-5")  # 9 AM on weekdays
def send_report():
    print("Daily report sent")

# That's it! 🎉
scheduler = PyScheduler()
scheduler.start()
```

## 📋 **Usage Examples**

### **Simple Tasks**
```python
from pyscheduler import task, daily, startup

@task(30)  # Every 30 seconds
def health_check():
    return check_system_health()

@daily("02:00")  # Every day at 2 AM
def daily_backup():
    return backup_database()

@startup()  # On startup
def init_app():
    return initialize_application()
```

### **Advanced Configuration**
```python
from pyscheduler import PyScheduler
from pyscheduler.config import RetryConfig, Priority

scheduler = PyScheduler(log_level="INFO")

scheduler.add_task(
    func=critical_task,
    interval=300,  # 5 minutes
    priority=Priority.CRITICAL,
    timeout=60,
    retry_config=RetryConfig(max_attempts=3, backoff_factor=2.0)
)
```

### **YAML Configuration**
```yaml
# scheduler_config.yaml
global_settings:
  timezone: "Europe/Paris"
  log_level: "INFO"
  max_workers: 10

tasks:
  - name: "backup_task"
    module: "myapp.tasks"
    function: "backup_database"
    schedule:
      type: "cron"
      value: "0 2 * * *"  # 2 AM
    priority: "HIGH"
    timeout: 3600
```

```python
scheduler = PyScheduler(config_file="scheduler_config.yaml")
scheduler.start()
```

## 🎪 **Use Cases**

| Need | PyScheduler Solution |
|--------|---------------------|
| 🔄 **Periodic Tasks** | `@task(interval=60)` |
| ⏰ **Precise Scheduling** | `@task(cron="0 9 * * 1-5")` |
| 🚀 **Startup/Shutdown Tasks** | `@startup()` / `@shutdown()` |
| ⚡ **Asynchronous Tasks** | Native `async def` support |
| 🛡️ **Robustness** | Automatic retry, timeouts |
| 📊 **Production** | Logs, stats, monitoring |

## 📚 **Full Documentation**

- 📖 **[Complete Guide](https://github.com/Tiger-Foxx/PyScheduler/blob/main/docs/)**
- 🎯 **[Detailed Examples](https://github.com/Tiger-Foxx/PyScheduler/tree/main/examples)**
- 🔧 **[API Reference](https://pyscheduler.readthedocs.io/)**
- ❓ **[FAQ & Troubleshooting](https://github.com/Tiger-Foxx/PyScheduler/blob/main/docs/troubleshooting.md)**

## 🏃‍♂️ **Quick Examples**

### **Get started with included examples**
```bash
# After installation
python -c "from pyscheduler.examples import basic_usage; basic_usage.main()"
```

### **Real-time Monitoring**
```python
with PyScheduler() as scheduler:
    # Your tasks here
    scheduler.run_forever()  # Ctrl+C to stop
```

## 🚀 **Advanced Features**

<details>
<summary>🎯 <strong>Priorities and Threading</strong></summary>

```python
from pyscheduler.config import Priority

@task(interval=60, priority=Priority.CRITICAL)
def critical_health_check():
    return monitor_critical_systems()

@task(interval=300, priority=Priority.LOW)
def cleanup_temp_files():
    return cleanup_operations()
```
</details>

<details>
<summary>⚡ <strong>Asynchronous Tasks</strong></summary>

```python
@task(interval=30)
async def async_api_calls():
    async with aiohttp.ClientSession() as session:
        tasks = [fetch_data(session, url) for url in urls]
        return await asyncio.gather(*tasks)
```
</details>

<details>
<summary>🛡️ <strong>Robust Error Handling</strong></summary>

```python
from pyscheduler.config import RetryConfig

@task(
    interval=120,
    retry_config=RetryConfig(
        max_attempts=5,
        backoff_factor=2.0,
        max_delay=300
    ),
    timeout=60
)
def unreliable_external_api():
    return call_external_service()
```
</details>

## 🔥 **Why PyScheduler?**

| Problem | PyScheduler Solution |
|----------|---------------------|
| 😩 **APScheduler too complex** | ✅ 3 lines to get started |
| 🐌 **Celery is overkill** | ✅ Zero configuration Redis/broker |
| 🔧 **Cron is limited** | ✅ Native Python + cron expressions |
| 📊 **No monitoring** | ✅ Detailed logs + statistics |
| 🚫 **No retry** | ✅ Smart retry built-in |

## 🏆 **Performance**

- ⚡ **Startup**: < 100ms
- 💾 **Memory**: < 20MB for 100 tasks
- 🔄 **Concurrency**: Up to 1000 parallel tasks
- 🎯 **Precision**: ±50ms on schedules

## 🤝 **Contributing**

We welcome all contributions!

```bash
git clone https://github.com/Tiger-Foxx/PyScheduler.git
cd PyScheduler
pip install -e .[dev]
pytest
```

## 📄 **License**

MIT License - see [LICENSE](LICENSE) for details.

## 🙏 **Acknowledgments**

Inspired by the best scheduling tools, designed for Pythonic simplicity.

---

**⭐ If PyScheduler helps you, feel free to star the repo!**

[🏠 Homepage](https://github.com/Tiger-Foxx/PyScheduler) • [📚 Documentation](https://pyscheduler.readthedocs.io/) • [🐛 Issues](https://github.com/Tiger-Foxx/PyScheduler/issues) • [💬 Discussions](https://github.com/Tiger-Foxx/PyScheduler/discussions)