Metadata-Version: 2.4
Name: jplan
Version: 1.0.0
Summary: A command-line tool to schedule and execute Jupyter notebooks using cron
Project-URL: Homepage, https://github.com/apoplexi24/jplan
Project-URL: Documentation, https://github.com/apoplexi24/jplan#readme
Project-URL: Repository, https://github.com/apoplexi24/jplan.git
Project-URL: Issues, https://github.com/apoplexi24/jplan/issues
Author-email: apoplexi24 <shivanandanasharma@gmail.com>
License-Expression: MIT
Keywords: cron,jupyter,notebook,papermill,scheduling
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.8
Requires-Dist: jupyter>=1.0.0
Requires-Dist: papermill>=2.4.0
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: isort>=5.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# jplan

A command-line tool to schedule and execute Jupyter notebooks using cron.

## Installation

This package uses `uv` for package management. To install:

```bash
# Install uv if you haven't already
pip install uv

# Create a virtual environment and install dependencies
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e .
```

## Usage

### Command Line Interface

The simplest way to use jplan is through the command line:

```bash
# Run notebook every hour with default log file in notebook's directory
jplan "0 * * * *" input.ipynb

# Run notebook every hour with specific log file (positional argument)
jplan "0 * * * *" input.ipynb output.log

# Run notebook every hour with specific log file (keyword argument)
jplan "0 * * * *" input.ipynb --log-file output.log

# Run notebook every hour with specific kernel
jplan "0 * * * *" input.ipynb --kernel python3

# Run notebook every 15 minutes
jplan "*/15 * * * *" input.ipynb

# Run notebook with custom output directory
jplan "0 * * * *" input.ipynb --output-dir /path/to/output

# Run notebook with parameters
jplan "0 * * * *" input.ipynb --parameters '{"param1": "value1", "param2": 42}'
```

The command takes the following arguments:
- `schedule`: Cron schedule expression (e.g., "0 * * * *" for hourly)
- `notebook`: Path to the input notebook file
- `log_file`: (Optional) Path to the log file (can be specified as positional or --log-file argument)
- `--output-dir`: (Optional) Directory to save executed notebooks
- `--parameters`: (Optional) JSON string of parameters to pass to the notebook
- `--kernel`: (Optional) Name of the kernel to use for execution

### Python API

You can also use the package programmatically:

```python
from jplan.executor import execute_notebook

# Execute a notebook with default settings
execute_notebook(
    input_path="path/to/input.ipynb"
)

# Execute a notebook with custom settings
execute_notebook(
    input_path="path/to/input.ipynb",
    output_path="path/to/output.ipynb",  # optional
    parameters={"param1": "value1", "param2": 42},  # optional
    kernel_name="python3",  # optional
    log_file="path/to/output.log"  # optional
)

# Create a cron job
from jplan.cron import create_cron_job

create_cron_job(
    notebook_path="path/to/input.ipynb",
    schedule="0 * * * *",  # Run at the start of every hour
    output_dir="path/to/output",  # optional
    parameters={"param1": "value1"},  # optional
    kernel_name="python3",  # optional
    log_file="path/to/output.log"  # optional
)
```

The schedule parameter uses standard cron syntax:
- `* * * * *` represents: minute hour day-of-month month day-of-week
- Examples:
  - `0 * * * *` - Run at the start of every hour
  - `0 0 * * *` - Run at midnight every day
  - `*/15 * * * *` - Run every 15 minutes

The executed notebooks will be saved with "_executed" appended to the filename, and a log file will be created in the output directory.

## Development

To install development dependencies:

```bash
uv pip install -e ".[dev]"
```

## License

MIT 