pemexe

Name	pemexe JSON
Version	1.5.1 JSON
	download
home_page	None
Summary	🚀 Python Execution Manager - A powerful, modern tool for managing, scheduling, and executing Python scripts and projects with comprehensive logging, flexible scheduling, and dependency management. Perfect for DevOps, data science, and automation workflows.
upload_time	2025-09-01 15:18:17
maintainer	None
docs_url	None
author	None
requires_python	>=3.13
license	MIT License Copyright (c) 2025 Arian Omrani Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
keywords	automation background-jobs cli cron dependencies devops execution logging management projects python scheduler scripts task-runner
VCS
bugtrack_url
requirements	No requirements were recorded.
Travis-CI	No Travis.
coveralls test coverage	No coveralls.

            # PEM - Python Execution Manager 🚀

**A powerful, modern CLI tool for managing, scheduling, and executing Python scripts and projects with ease.**

[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Built with uv](https://img.shields.io/badge/built%20with-uv-blue)](https://github.com/astral-sh/uv)

## ✨ What is PEM?

PEM (Python Execution Manager) is your comprehensive solution for managing Python script and project execution. Whether you need to run scripts on-demand, schedule automated tasks, or manage complex Python workflows, PEM provides an intuitive CLI interface with powerful scheduling capabilities.

### 🎯 Perfect for:
- **Data Scientists** scheduling ETL pipelines and analysis scripts
- **DevOps Engineers** automating deployment and maintenance tasks
- **Python Developers** managing multiple projects and scripts
- **System Administrators** running scheduled monitoring and backup tasks
- **Anyone** who needs reliable Python execution with proper logging and scheduling

## 🌟 Key Features

### 📋 **Unified Job Management**
- **Two Job Types**: Handle both standalone Python scripts and full projects
- **Smart Auto-execution**: Automatically run jobs after creation (configurable)
- **Dependency Management**: Specify Python dependencies for script-type jobs
- **Enable/Disable Control**: Easy job activation and deactivation

### ⏰ **Flexible Scheduling System**
- **Multiple Schedule Types**:
  - `once` - Execute at a specific date/time
  - `interval` - Run every X seconds/minutes/hours/days
  - `cron` - Use cron-style expressions for complex schedules
  - `until_done` - Retry until successful execution
- **Unified Execution**: Single `run` command for immediate + optional scheduling
- **Background Processing**: All scheduled jobs run automatically in the background

### 📊 **Comprehensive Monitoring & Logging**
- **Detailed Execution Logs**: Every run logged with timestamps, status, and output
- **Real-time Status**: View system overview with job counts and schedules
- **SQLite Database**: Persistent local storage for all jobs and execution history
- **Rich CLI Output**: Color-coded feedback with emojis for better UX

### 🛠 **Developer-Friendly Interface**
- **Intuitive Commands**: Simple, memorable command structure
- **Type-safe CLI**: Built with modern Typer framework
- **Clean Help Output**: No clutter - only essential information shown
- **Actionable Error Messages**: Clear guidance when things go wrong

## 🚀 Quick Start

### Installation Options

#### Option 1: Using UV (Recommended)
```bash
# Install UV if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install PEM from PyPI
uv tool install pemexe

# Or install from source
git clone https://github.com/yourusername/pem.git
cd pem
uv sync
uv run pem --help
```

#### Option 2: Using pip
```bash
pip install pemexe
```

#### Option 3: Download Binary
```bash
# Download the latest binary from releases
wget https://github.com/yourusername/pem/releases/latest/download/pem
chmod +x pem
sudo mv pem /usr/local/bin/
```

### Development Setup

```bash
# Clone the repository
git clone https://github.com/yourusername/pem.git
cd pem

# Install development dependencies
make dev-install
# or manually:
uv sync --group dev --group build --group release

# Run tests
make test

# Build the project
make build

# Build standalone binary
make binary
```

### Installation
```bash
# If using in your project
uv add pemexe
# OR
pip install pemexe

# If using as tool
uvx --from pemexe pem
```


```bash
# Clone and install locally
git clone https://github.com/arian24b/pem.git
cd pem
uv sync

# Or install from source
pip install -e .
```

### Basic Usage

```bash
# Add and run a Python script immediately
pem add --path ./my_script.py --script --name "data-processor"

# Add a project without auto-execution
pem add --path ./my_project --name "web-app" --no-auto-run

# Execute an existing job
pem run --name "data-processor"

# Execute and schedule for hourly runs
pem run --name "data-processor" --schedule --type interval --minutes 60

# View all jobs
pem show

# Check system status
pem status
```

## 📖 Command Reference

### Job Management Commands

#### `pem add` - Create New Jobs
Create a new job to execute Python scripts or projects.

```bash
# Add a simple script with dependencies
pem add --path ./script.py --script --name "analyzer" --with pandas requests

# Add a project (uses existing environment)
pem add --path ./my_project --name "web-server"

# Add disabled job (no auto-execution)
pem add --path ./script.py --script --disabled --no-auto-run

# Add with specific Python version
pem add --path ./script.py --script --python 3.11 --with numpy
```

**Key Options:**
- `--path`, `-p`: Path to Python script or project directory *(required)*
- `--name`, `-n`: Unique job name (auto-generated if not provided)
- `--script`, `-s`: Treat as single Python script (vs. project)
- `--with`, `-w`: Python dependencies to install (scripts only)
- `--python`, `-v`: Required Python version (scripts only)
- `--enabled/--disabled`, `-e`: Enable/disable job execution
- `--auto-run/--no-auto-run`: Execute immediately after creation

#### `pem show` - Display Job Information
Display details of jobs (all jobs if no filter specified).

```bash
# Show all jobs
pem show

# Show specific job by name
pem show --name "data-processor"

# Show specific job by ID
pem show --id 1
```

#### `pem update` - Modify Existing Jobs
Update properties of an existing job.

```bash
# Enable a disabled job
pem update --name "data-processor" --enabled

# Update job path
pem update --id 1 --path ./new_script.py

# Change job type and dependencies
pem update --name "analyzer" --script --with pandas numpy matplotlib
```

#### `pem delete` - Remove Jobs
Remove a job permanently from the system.

```bash
# Delete by name
pem delete --name "old-job"

# Delete by ID
pem delete --id 1
```

### Execution Commands

#### `pem run` - Execute Jobs (Immediate + Optional Scheduling)
Execute a job immediately, with optional recurring schedule setup.

```bash
# Execute job immediately
pem run --name "data-processor"

# Execute and set up hourly schedule
pem run --name "monitor" --schedule --type interval --minutes 60

# Execute by ID with daily schedule
pem run --id 1 --schedule --type interval --minutes 1440
```

**Key Options:**
- `--id`, `-i`: ID of job to execute
- `--name`, `-n`: Name of job to execute
- `--schedule/--no-schedule`, `-s`: Set up recurring schedule
- `--type`, `-t`: Schedule type (interval, once, cron, until_done)
- `--minutes`, `-m`: Interval in minutes (for interval scheduling)

### Scheduling Commands

#### `pem cron` - Advanced Job Scheduling
Schedule a job for automatic execution using various timing options.

```bash
# Schedule every 30 minutes
pem cron --name "monitor" --type interval --minutes 30

# Schedule daily at 9 AM using cron
pem cron --name "report" --type cron --cron-hour 9 --cron-minute 0

# Schedule one-time execution
pem cron --name "backup" --type once --date "2024-12-31T23:59:59"

# Retry until success
pem cron --name "flaky-job" --type until_done --max-retries 5 --retry-interval 300
```

**Schedule Types:**
- **interval**: `--seconds`, `--minutes`, `--hours`, `--days`
- **once**: `--date` (ISO format: 2024-01-01T10:00:00)
- **cron**: `--cron-minute`, `--cron-hour`, `--cron-day`, `--cron-month`, `--cron-dow`
- **until_done**: `--max-retries`, `--retry-interval`

#### `pem crons` - List Scheduled Jobs
List all jobs currently scheduled for automatic execution.

```bash
pem crons
```

#### `pem cancel` - Cancel Scheduled Jobs
Cancel a scheduled job by its scheduler ID.

```bash
# Cancel specific scheduled job (use ID from 'pem crons')
pem cancel --scheduler-id "pem_job_interval_1_20241201_120000"
```

### System Commands

#### `pem status` - System Overview
Display system overview with job counts and scheduling statistics.

```bash
pem status
```

Shows:
- Total jobs (enabled/disabled, scripts/projects)
- Active scheduled jobs with next run times
- System health at a glance

## 🏗 Architecture & Design

PEM is built with modern Python technologies:

- **AsyncTyper**: Custom async CLI framework extending Typer
- **SQLAlchemy**: Robust async database ORM for data persistence
- **APScheduler**: Reliable background job scheduling
- **Faker**: Automatic job name generation
- **AsyncIO**: Efficient asynchronous execution throughout

### Database Schema
- **Jobs Table**: Stores job definitions, paths, dependencies, and settings
- **Execution History**: Tracks all job runs with status, logs, and timing
- **Schedule Tracking**: Manages active schedules and their configurations

## 🔧 Configuration & Setup

PEM works out of the box with minimal configuration:

- **Database**: SQLite (`pem.db`) in working directory
- **Logs**: Stored in `./logs/` with timestamped filenames
- **Auto-initialization**: Database and tables created automatically
- **Environment Isolation**: Uses proper Python environment handling

## 📁 Project Structure

```
pem/
├── pem/
│   ├── cli.py              # Main CLI interface with all commands
│   ├── settings.py         # Configuration and settings
│   ├── core/
│   │   ├── executor.py     # Job execution engine
│   │   └── scheduler.py    # Background scheduling manager
│   └── db/
│       ├── database.py     # Database configuration & sessions
│       └── models.py       # SQLAlchemy data models
├── logs/                   # Execution logs directory
├── pem.db                 # SQLite database file
└── pyproject.toml         # Project configuration with uv
```

## � Common Workflows

### 1. Quick Script Development & Testing
```bash
# Add and test a script immediately
pem add --path ./analysis.py --script --name "analysis" --with pandas

# Iterate and re-run during development
pem run --name "analysis"
```

### 2. Production Data Pipeline Setup
```bash
# Add ETL script
pem add --path ./etl_pipeline.py --script --name "daily-etl" --no-auto-run

# Schedule for daily execution at 2 AM
pem cron --name "daily-etl" --type cron --cron-hour 2 --cron-minute 0

# Monitor scheduled jobs
pem crons
pem status
```

### 3. System Monitoring Setup
```bash
# Add monitoring script
pem add --path ./health_check.py --script --name "health-monitor" --no-auto-run

# Set up 5-minute monitoring
pem cron --name "health-monitor" --type interval --minutes 5

# Check system status
pem status
```

### 4. Project Management
```bash
# Add a Python project
pem add --path ./my_fastapi_app --name "api-server" --no-auto-run

# Run when needed
pem run --name "api-server"

# Update project path as it evolves
pem update --name "api-server" --path ./updated_fastapi_app
```

## 🛠 Development & Contributing

### Development Workflow

This project uses **UV** for modern Python package management and follows best practices for professional Python development.

#### Quick Development Commands
```bash
# Install all dependencies (dev, build, release)
make dev-install

# Run code quality checks
make lint

# Format code
make format

# Run tests with coverage
make test

# Build Python package
make build

# Build standalone binary
make binary

# Full release process
make release
```

#### Manual UV Commands
```bash
# Install project and dependencies
uv sync

# Install specific dependency groups
uv sync --group dev          # Development tools
uv sync --group build        # Build tools
uv sync --group release      # Release tools

# Run commands in the UV environment
uv run pem --help           # Run PEM
uv run pytest              # Run tests
uv run ruff check pem/      # Lint code
uv run mypy pem/            # Type check

# Build and publish
uv build                    # Build wheel and source dist
uv publish --token $TOKEN   # Publish to PyPI
```

#### Project Structure
```
pem/
├── pem/                    # Main package
│   ├── cli.py             # CLI interface
│   ├── settings.py        # Configuration
│   ├── core/              # Core scheduling logic
│   └── db/                # Database models
├── scripts/               # Build and release scripts
│   ├── build_binary.py    # PyInstaller automation
│   └── release.py         # Release automation
├── pyproject.toml         # Project configuration
├── uv.toml                # UV configuration
├── uv.lock                # Dependency lock file
└── Makefile               # Development shortcuts
```

#### Release Process

```bash
# Option 1: Automated release
python scripts/release.py

# Option 2: Manual steps
make lint test              # Quality checks
make build                  # Build package
make binary                 # Build binary
uv publish --token $TOKEN   # Publish to PyPI
```

#### Configuration Files

- **pyproject.toml**: Main project configuration with modern PEP 518/621 standards
- **uv.toml**: UV-specific settings for dependency resolution and publishing
- **uv.lock**: Reproducible dependency versions
- **Makefile**: Development shortcuts and common commands

## 🆚 Why Choose PEM?

### vs. Cron/Task Scheduler
- ✅ **Cross-platform**: Works identically on Windows, macOS, and Linux
- ✅ **Python-native**: No shell scripting required
- ✅ **Dependency management**: Built-in package handling
- ✅ **Rich logging**: Detailed execution history and status tracking
- ✅ **User-friendly**: Modern CLI with helpful error messages

### vs. Other Python Task Runners
- ✅ **Zero configuration**: Works immediately without complex setup files
- ✅ **Local storage**: No external databases or services required
- ✅ **Unified interface**: Single tool for all execution needs
- ✅ **Flexible scheduling**: Multiple timing patterns in one tool
- ✅ **Developer UX**: Intuitive commands with excellent error handling

### vs. Manual Script Management
- ✅ **Automated scheduling**: Set-and-forget execution
- ✅ **Centralized management**: All scripts in one place
- ✅ **Execution tracking**: History, logs, and status monitoring
- ✅ **Error handling**: Retry mechanisms and failure notifications
- ✅ **Environment isolation**: Proper dependency and version management

## 🤝 Contributing

We welcome contributions! To get started:

1. **Fork the repository**
2. **Create a feature branch**: `git checkout -b feature/amazing-feature`
3. **Make your changes** with tests
4. **Run the test suite**: `pytest`
5. **Submit a pull request**

### Development Setup
```bash
git clone https://github.com/arian24b/pem.git
cd pem
uv sync
```

## 📝 License

MIT License - see [LICENSE](LICENSE) file for details.

## 🙋‍♀️ Support & Community

- **Issues**: [GitHub Issues](https://github.com/arian24b/pem/issues)
- **Feature Requests**: [GitHub Discussions](https://github.com/arian24b/pem/discussions)
- **Documentation**: See the comprehensive [Tool Overview](PEM_TOOL_OVERVIEW.md)

---

**Made with ❤️ by [Arian Omrani](https://github.com/arian24b)**

*PEM - Schedule and execute Python scripts and projects with ease* 🐍✨

            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "pemexe",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.13",
    "maintainer_email": "Arian Omrani <arian24b@gmail.com>",
    "keywords": "automation, background-jobs, cli, cron, dependencies, devops, execution, logging, management, projects, python, scheduler, scripts, task-runner",
    "author": null,
    "author_email": "Arian Omrani <arian24b@gmail.com>",
    "download_url": "https://files.pythonhosted.org/packages/8c/b9/c803fe025147a7f0f86eeec7b1bd8521987a1152934b75a4369e81c75603/pemexe-1.5.1.tar.gz",
    "platform": null,
    "description": "# PEM - Python Execution Manager \ud83d\ude80\n\n**A powerful, modern CLI tool for managing, scheduling, and executing Python scripts and projects with ease.**\n\n[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Built with uv](https://img.shields.io/badge/built%20with-uv-blue)](https://github.com/astral-sh/uv)\n\n## \u2728 What is PEM?\n\nPEM (Python Execution Manager) is your comprehensive solution for managing Python script and project execution. Whether you need to run scripts on-demand, schedule automated tasks, or manage complex Python workflows, PEM provides an intuitive CLI interface with powerful scheduling capabilities.\n\n### \ud83c\udfaf Perfect for:\n- **Data Scientists** scheduling ETL pipelines and analysis scripts\n- **DevOps Engineers** automating deployment and maintenance tasks\n- **Python Developers** managing multiple projects and scripts\n- **System Administrators** running scheduled monitoring and backup tasks\n- **Anyone** who needs reliable Python execution with proper logging and scheduling\n\n## \ud83c\udf1f Key Features\n\n### \ud83d\udccb **Unified Job Management**\n- **Two Job Types**: Handle both standalone Python scripts and full projects\n- **Smart Auto-execution**: Automatically run jobs after creation (configurable)\n- **Dependency Management**: Specify Python dependencies for script-type jobs\n- **Enable/Disable Control**: Easy job activation and deactivation\n\n### \u23f0 **Flexible Scheduling System**\n- **Multiple Schedule Types**:\n  - `once` - Execute at a specific date/time\n  - `interval` - Run every X seconds/minutes/hours/days\n  - `cron` - Use cron-style expressions for complex schedules\n  - `until_done` - Retry until successful execution\n- **Unified Execution**: Single `run` command for immediate + optional scheduling\n- **Background Processing**: All scheduled jobs run automatically in the background\n\n### \ud83d\udcca **Comprehensive Monitoring & Logging**\n- **Detailed Execution Logs**: Every run logged with timestamps, status, and output\n- **Real-time Status**: View system overview with job counts and schedules\n- **SQLite Database**: Persistent local storage for all jobs and execution history\n- **Rich CLI Output**: Color-coded feedback with emojis for better UX\n\n### \ud83d\udee0 **Developer-Friendly Interface**\n- **Intuitive Commands**: Simple, memorable command structure\n- **Type-safe CLI**: Built with modern Typer framework\n- **Clean Help Output**: No clutter - only essential information shown\n- **Actionable Error Messages**: Clear guidance when things go wrong\n\n## \ud83d\ude80 Quick Start\n\n### Installation Options\n\n#### Option 1: Using UV (Recommended)\n```bash\n# Install UV if you haven't already\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# Install PEM from PyPI\nuv tool install pemexe\n\n# Or install from source\ngit clone https://github.com/yourusername/pem.git\ncd pem\nuv sync\nuv run pem --help\n```\n\n#### Option 2: Using pip\n```bash\npip install pemexe\n```\n\n#### Option 3: Download Binary\n```bash\n# Download the latest binary from releases\nwget https://github.com/yourusername/pem/releases/latest/download/pem\nchmod +x pem\nsudo mv pem /usr/local/bin/\n```\n\n### Development Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/yourusername/pem.git\ncd pem\n\n# Install development dependencies\nmake dev-install\n# or manually:\nuv sync --group dev --group build --group release\n\n# Run tests\nmake test\n\n# Build the project\nmake build\n\n# Build standalone binary\nmake binary\n```\n\n### Installation\n```bash\n# If using in your project\nuv add pemexe\n# OR\npip install pemexe\n\n# If using as tool\nuvx --from pemexe pem\n```\n\n\n```bash\n# Clone and install locally\ngit clone https://github.com/arian24b/pem.git\ncd pem\nuv sync\n\n# Or install from source\npip install -e .\n```\n\n### Basic Usage\n\n```bash\n# Add and run a Python script immediately\npem add --path ./my_script.py --script --name \"data-processor\"\n\n# Add a project without auto-execution\npem add --path ./my_project --name \"web-app\" --no-auto-run\n\n# Execute an existing job\npem run --name \"data-processor\"\n\n# Execute and schedule for hourly runs\npem run --name \"data-processor\" --schedule --type interval --minutes 60\n\n# View all jobs\npem show\n\n# Check system status\npem status\n```\n\n## \ud83d\udcd6 Command Reference\n\n### Job Management Commands\n\n#### `pem add` - Create New Jobs\nCreate a new job to execute Python scripts or projects.\n\n```bash\n# Add a simple script with dependencies\npem add --path ./script.py --script --name \"analyzer\" --with pandas requests\n\n# Add a project (uses existing environment)\npem add --path ./my_project --name \"web-server\"\n\n# Add disabled job (no auto-execution)\npem add --path ./script.py --script --disabled --no-auto-run\n\n# Add with specific Python version\npem add --path ./script.py --script --python 3.11 --with numpy\n```\n\n**Key Options:**\n- `--path`, `-p`: Path to Python script or project directory *(required)*\n- `--name`, `-n`: Unique job name (auto-generated if not provided)\n- `--script`, `-s`: Treat as single Python script (vs. project)\n- `--with`, `-w`: Python dependencies to install (scripts only)\n- `--python`, `-v`: Required Python version (scripts only)\n- `--enabled/--disabled`, `-e`: Enable/disable job execution\n- `--auto-run/--no-auto-run`: Execute immediately after creation\n\n#### `pem show` - Display Job Information\nDisplay details of jobs (all jobs if no filter specified).\n\n```bash\n# Show all jobs\npem show\n\n# Show specific job by name\npem show --name \"data-processor\"\n\n# Show specific job by ID\npem show --id 1\n```\n\n#### `pem update` - Modify Existing Jobs\nUpdate properties of an existing job.\n\n```bash\n# Enable a disabled job\npem update --name \"data-processor\" --enabled\n\n# Update job path\npem update --id 1 --path ./new_script.py\n\n# Change job type and dependencies\npem update --name \"analyzer\" --script --with pandas numpy matplotlib\n```\n\n#### `pem delete` - Remove Jobs\nRemove a job permanently from the system.\n\n```bash\n# Delete by name\npem delete --name \"old-job\"\n\n# Delete by ID\npem delete --id 1\n```\n\n### Execution Commands\n\n#### `pem run` - Execute Jobs (Immediate + Optional Scheduling)\nExecute a job immediately, with optional recurring schedule setup.\n\n```bash\n# Execute job immediately\npem run --name \"data-processor\"\n\n# Execute and set up hourly schedule\npem run --name \"monitor\" --schedule --type interval --minutes 60\n\n# Execute by ID with daily schedule\npem run --id 1 --schedule --type interval --minutes 1440\n```\n\n**Key Options:**\n- `--id`, `-i`: ID of job to execute\n- `--name`, `-n`: Name of job to execute\n- `--schedule/--no-schedule`, `-s`: Set up recurring schedule\n- `--type`, `-t`: Schedule type (interval, once, cron, until_done)\n- `--minutes`, `-m`: Interval in minutes (for interval scheduling)\n\n### Scheduling Commands\n\n#### `pem cron` - Advanced Job Scheduling\nSchedule a job for automatic execution using various timing options.\n\n```bash\n# Schedule every 30 minutes\npem cron --name \"monitor\" --type interval --minutes 30\n\n# Schedule daily at 9 AM using cron\npem cron --name \"report\" --type cron --cron-hour 9 --cron-minute 0\n\n# Schedule one-time execution\npem cron --name \"backup\" --type once --date \"2024-12-31T23:59:59\"\n\n# Retry until success\npem cron --name \"flaky-job\" --type until_done --max-retries 5 --retry-interval 300\n```\n\n**Schedule Types:**\n- **interval**: `--seconds`, `--minutes`, `--hours`, `--days`\n- **once**: `--date` (ISO format: 2024-01-01T10:00:00)\n- **cron**: `--cron-minute`, `--cron-hour`, `--cron-day`, `--cron-month`, `--cron-dow`\n- **until_done**: `--max-retries`, `--retry-interval`\n\n#### `pem crons` - List Scheduled Jobs\nList all jobs currently scheduled for automatic execution.\n\n```bash\npem crons\n```\n\n#### `pem cancel` - Cancel Scheduled Jobs\nCancel a scheduled job by its scheduler ID.\n\n```bash\n# Cancel specific scheduled job (use ID from 'pem crons')\npem cancel --scheduler-id \"pem_job_interval_1_20241201_120000\"\n```\n\n### System Commands\n\n#### `pem status` - System Overview\nDisplay system overview with job counts and scheduling statistics.\n\n```bash\npem status\n```\n\nShows:\n- Total jobs (enabled/disabled, scripts/projects)\n- Active scheduled jobs with next run times\n- System health at a glance\n\n## \ud83c\udfd7 Architecture & Design\n\nPEM is built with modern Python technologies:\n\n- **AsyncTyper**: Custom async CLI framework extending Typer\n- **SQLAlchemy**: Robust async database ORM for data persistence\n- **APScheduler**: Reliable background job scheduling\n- **Faker**: Automatic job name generation\n- **AsyncIO**: Efficient asynchronous execution throughout\n\n### Database Schema\n- **Jobs Table**: Stores job definitions, paths, dependencies, and settings\n- **Execution History**: Tracks all job runs with status, logs, and timing\n- **Schedule Tracking**: Manages active schedules and their configurations\n\n## \ud83d\udd27 Configuration & Setup\n\nPEM works out of the box with minimal configuration:\n\n- **Database**: SQLite (`pem.db`) in working directory\n- **Logs**: Stored in `./logs/` with timestamped filenames\n- **Auto-initialization**: Database and tables created automatically\n- **Environment Isolation**: Uses proper Python environment handling\n\n## \ud83d\udcc1 Project Structure\n\n```\npem/\n\u251c\u2500\u2500 pem/\n\u2502   \u251c\u2500\u2500 cli.py              # Main CLI interface with all commands\n\u2502   \u251c\u2500\u2500 settings.py         # Configuration and settings\n\u2502   \u251c\u2500\u2500 core/\n\u2502   \u2502   \u251c\u2500\u2500 executor.py     # Job execution engine\n\u2502   \u2502   \u2514\u2500\u2500 scheduler.py    # Background scheduling manager\n\u2502   \u2514\u2500\u2500 db/\n\u2502       \u251c\u2500\u2500 database.py     # Database configuration & sessions\n\u2502       \u2514\u2500\u2500 models.py       # SQLAlchemy data models\n\u251c\u2500\u2500 logs/                   # Execution logs directory\n\u251c\u2500\u2500 pem.db                 # SQLite database file\n\u2514\u2500\u2500 pyproject.toml         # Project configuration with uv\n```\n\n## \ufffd Common Workflows\n\n### 1. Quick Script Development & Testing\n```bash\n# Add and test a script immediately\npem add --path ./analysis.py --script --name \"analysis\" --with pandas\n\n# Iterate and re-run during development\npem run --name \"analysis\"\n```\n\n### 2. Production Data Pipeline Setup\n```bash\n# Add ETL script\npem add --path ./etl_pipeline.py --script --name \"daily-etl\" --no-auto-run\n\n# Schedule for daily execution at 2 AM\npem cron --name \"daily-etl\" --type cron --cron-hour 2 --cron-minute 0\n\n# Monitor scheduled jobs\npem crons\npem status\n```\n\n### 3. System Monitoring Setup\n```bash\n# Add monitoring script\npem add --path ./health_check.py --script --name \"health-monitor\" --no-auto-run\n\n# Set up 5-minute monitoring\npem cron --name \"health-monitor\" --type interval --minutes 5\n\n# Check system status\npem status\n```\n\n### 4. Project Management\n```bash\n# Add a Python project\npem add --path ./my_fastapi_app --name \"api-server\" --no-auto-run\n\n# Run when needed\npem run --name \"api-server\"\n\n# Update project path as it evolves\npem update --name \"api-server\" --path ./updated_fastapi_app\n```\n\n## \ud83d\udee0 Development & Contributing\n\n### Development Workflow\n\nThis project uses **UV** for modern Python package management and follows best practices for professional Python development.\n\n#### Quick Development Commands\n```bash\n# Install all dependencies (dev, build, release)\nmake dev-install\n\n# Run code quality checks\nmake lint\n\n# Format code\nmake format\n\n# Run tests with coverage\nmake test\n\n# Build Python package\nmake build\n\n# Build standalone binary\nmake binary\n\n# Full release process\nmake release\n```\n\n#### Manual UV Commands\n```bash\n# Install project and dependencies\nuv sync\n\n# Install specific dependency groups\nuv sync --group dev          # Development tools\nuv sync --group build        # Build tools\nuv sync --group release      # Release tools\n\n# Run commands in the UV environment\nuv run pem --help           # Run PEM\nuv run pytest              # Run tests\nuv run ruff check pem/      # Lint code\nuv run mypy pem/            # Type check\n\n# Build and publish\nuv build                    # Build wheel and source dist\nuv publish --token $TOKEN   # Publish to PyPI\n```\n\n#### Project Structure\n```\npem/\n\u251c\u2500\u2500 pem/                    # Main package\n\u2502   \u251c\u2500\u2500 cli.py             # CLI interface\n\u2502   \u251c\u2500\u2500 settings.py        # Configuration\n\u2502   \u251c\u2500\u2500 core/              # Core scheduling logic\n\u2502   \u2514\u2500\u2500 db/                # Database models\n\u251c\u2500\u2500 scripts/               # Build and release scripts\n\u2502   \u251c\u2500\u2500 build_binary.py    # PyInstaller automation\n\u2502   \u2514\u2500\u2500 release.py         # Release automation\n\u251c\u2500\u2500 pyproject.toml         # Project configuration\n\u251c\u2500\u2500 uv.toml                # UV configuration\n\u251c\u2500\u2500 uv.lock                # Dependency lock file\n\u2514\u2500\u2500 Makefile               # Development shortcuts\n```\n\n#### Release Process\n\n```bash\n# Option 1: Automated release\npython scripts/release.py\n\n# Option 2: Manual steps\nmake lint test              # Quality checks\nmake build                  # Build package\nmake binary                 # Build binary\nuv publish --token $TOKEN   # Publish to PyPI\n```\n\n#### Configuration Files\n\n- **pyproject.toml**: Main project configuration with modern PEP 518/621 standards\n- **uv.toml**: UV-specific settings for dependency resolution and publishing\n- **uv.lock**: Reproducible dependency versions\n- **Makefile**: Development shortcuts and common commands\n\n## \ud83c\udd9a Why Choose PEM?\n\n### vs. Cron/Task Scheduler\n- \u2705 **Cross-platform**: Works identically on Windows, macOS, and Linux\n- \u2705 **Python-native**: No shell scripting required\n- \u2705 **Dependency management**: Built-in package handling\n- \u2705 **Rich logging**: Detailed execution history and status tracking\n- \u2705 **User-friendly**: Modern CLI with helpful error messages\n\n### vs. Other Python Task Runners\n- \u2705 **Zero configuration**: Works immediately without complex setup files\n- \u2705 **Local storage**: No external databases or services required\n- \u2705 **Unified interface**: Single tool for all execution needs\n- \u2705 **Flexible scheduling**: Multiple timing patterns in one tool\n- \u2705 **Developer UX**: Intuitive commands with excellent error handling\n\n### vs. Manual Script Management\n- \u2705 **Automated scheduling**: Set-and-forget execution\n- \u2705 **Centralized management**: All scripts in one place\n- \u2705 **Execution tracking**: History, logs, and status monitoring\n- \u2705 **Error handling**: Retry mechanisms and failure notifications\n- \u2705 **Environment isolation**: Proper dependency and version management\n\n## \ud83e\udd1d Contributing\n\nWe welcome contributions! To get started:\n\n1. **Fork the repository**\n2. **Create a feature branch**: `git checkout -b feature/amazing-feature`\n3. **Make your changes** with tests\n4. **Run the test suite**: `pytest`\n5. **Submit a pull request**\n\n### Development Setup\n```bash\ngit clone https://github.com/arian24b/pem.git\ncd pem\nuv sync\n```\n\n## \ud83d\udcdd License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## \ud83d\ude4b\u200d\u2640\ufe0f Support & Community\n\n- **Issues**: [GitHub Issues](https://github.com/arian24b/pem/issues)\n- **Feature Requests**: [GitHub Discussions](https://github.com/arian24b/pem/discussions)\n- **Documentation**: See the comprehensive [Tool Overview](PEM_TOOL_OVERVIEW.md)\n\n---\n\n**Made with \u2764\ufe0f by [Arian Omrani](https://github.com/arian24b)**\n\n*PEM - Schedule and execute Python scripts and projects with ease* \ud83d\udc0d\u2728\n",
    "bugtrack_url": null,
    "license": "MIT License  Copyright (c) 2025 Arian Omrani  Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:  The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.  THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.",
    "summary": "\ud83d\ude80 Python Execution Manager - A powerful, modern tool for managing, scheduling, and executing Python scripts and projects with comprehensive logging, flexible scheduling, and dependency management. Perfect for DevOps, data science, and automation workflows.",
    "version": "1.5.1",
    "project_urls": {
        "Changelog": "https://github.com/arian24b/pem/blob/main/CHANGELOG.md",
        "Documentation": "https://github.com/arian24b/pem#readme",
        "Homepage": "https://github.com/arian24b/pem",
        "Issues": "https://github.com/arian24b/pem/issues",
        "Repository": "https://github.com/arian24b/pem.git"
    },
    "split_keywords": [
        "automation",
        " background-jobs",
        " cli",
        " cron",
        " dependencies",
        " devops",
        " execution",
        " logging",
        " management",
        " projects",
        " python",
        " scheduler",
        " scripts",
        " task-runner"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "3f59c8a885e92b0f746f1c3fc91fe4234ade504a8bd3f49a883bbd5bd81029c8",
                "md5": "cccc4c4ff3d9fad2c2ae4dcfa1f1da1c",
                "sha256": "5d9e4d04f59a69066fbc53346c5f1a5d34dde15afd86db23a048e3a6cec32005"
            },
            "downloads": -1,
            "filename": "pemexe-1.5.1-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "cccc4c4ff3d9fad2c2ae4dcfa1f1da1c",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.13",
            "size": 27891,
            "upload_time": "2025-09-01T15:18:16",
            "upload_time_iso_8601": "2025-09-01T15:18:16.115100Z",
            "url": "https://files.pythonhosted.org/packages/3f/59/c8a885e92b0f746f1c3fc91fe4234ade504a8bd3f49a883bbd5bd81029c8/pemexe-1.5.1-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "8cb9c803fe025147a7f0f86eeec7b1bd8521987a1152934b75a4369e81c75603",
                "md5": "28212ddfbabca0012a93f94c9108a602",
                "sha256": "86d8b4d0ae9ab12ef3da389d9a2edace6665e9b4cfefb338f2bde6f0586322f5"
            },
            "downloads": -1,
            "filename": "pemexe-1.5.1.tar.gz",
            "has_sig": false,
            "md5_digest": "28212ddfbabca0012a93f94c9108a602",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.13",
            "size": 31526,
            "upload_time": "2025-09-01T15:18:17",
            "upload_time_iso_8601": "2025-09-01T15:18:17.270884Z",
            "url": "https://files.pythonhosted.org/packages/8c/b9/c803fe025147a7f0f86eeec7b1bd8521987a1152934b75a4369e81c75603/pemexe-1.5.1.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-09-01 15:18:17",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "arian24b",
    "github_project": "pem",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "lcname": "pemexe"
}