Metadata-Version: 2.4
Name: pandaaas
Version: 0.1.0
Summary: A Python code exporter package for predefined experiment templates.
Author: pandaaas maintainers
Project-URL: Homepage, https://github.com/placeholder/pandaaas
Project-URL: Issues, https://github.com/placeholder/pandaaas/issues
Keywords: code-generator,templates,experiments,reproducibility
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Code Generators
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Dynamic: license-file

# pandaaas

A lightweight, safe Python code exporter package for predefined experiment templates.

`pandaaas` (with a double **a**) allows developers and researchers to export standardized, self-contained Python experiment templates directly into existing Python script files.

---

## What `pandaaas` Does

- Provides 8 predefined experiment template functions (`exp1` through `exp8`).
- Reads packaged, plain-text templates using `importlib.resources`.
- Normalizes indentation and line endings (ensuring standard Unix LF endings and a single trailing newline).
- Overwrites the entire contents of a specified existing Python file with the requested experiment code.
- Returns the destination `Path` object and prints a concise status confirmation.

---

## What `pandaaas` Deliberately Does NOT Do

To maintain safety, predictability, and minimal footprint:

- **NEVER executes code**: Templates are handled strictly as UTF-8 text. Generated code is never evaluated, executed, imported, or run via subprocesses.
- **NEVER creates new destination files**: If the target destination does not exist, `pandaaas` raises `FileNotFoundError`. You must create the file explicitly before exporting.
- **NEVER generates dependency files automatically**: `pandaaas` will never create or modify `requirements.txt` or environment files.
- **NEVER installs dependencies**: `pandaaas` will never run `pip` or manage your runtime environment.
- **NEVER fetches remote templates**: All templates are bundled locally within the package.
- **NEVER overwrites symlinks**: Symbolic links are rejected to avoid inadvertent overwrites outside the target scope.
- **NEVER touches unrelated files**: Only the explicitly provided target path is modified.

---

## Requirements and Compatibility

- **Python**: 3.10 or newer (tested on 3.10, 3.11, 3.12).
- **Runtime Dependencies**: Zero (pure Python standard library).

---

## Installation

Install the package via `pip`:

```bash
python -m pip install pandaaas
```

For local development and testing:

```bash
git clone https://github.com/placeholder/pandaaas.git
cd pandaaas
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
```

---

## Quick Start

> [!WARNING]
> Calling an experiment function **completely overwrites** the contents of the target file.
> Always ensure your target file is dedicated to the experiment or backed up if needed.

### 1. Create the destination file

`pandaaas` refuses to create new files automatically. You must ensure the destination file exists first:

```bash
# In your terminal:
touch experiment.py
```

Or in Python:

```python
from pathlib import Path
Path("experiment.py").touch()
```

### 2. Export an experiment

```python
import pandaaas as pd

# Export Experiment 1 template code into experiment.py
exported_path = pd.exp1(output_file="experiment.py")

print(f"Exported to: {exported_path}")
```

Output:
```text
[pandaaas] Exported Experiment 1 code to 'experiment.py'.
Exported to: experiment.py
```

---

## Public API Reference

All eight functions accept either a `str` or an `os.PathLike` path pointing to an existing `.py` file, optionally accept `quiet=True` to suppress stdout, and return a `pathlib.Path` pointing to the modified file.

| Function | Experiment Name | Description |
| :--- | :--- | :--- |
| `pd.exp1(output_file, *, quiet=False)` | Baseline Pipeline | Baseline model workflow template |
| `pd.exp2(output_file, *, quiet=False)` | Feature Engineering | Feature extraction and transformation template |
| `pd.exp3(output_file, *, quiet=False)` | Model Architecture | Alternative model architecture exploration template |
| `pd.exp4(output_file, *, quiet=False)` | Hyperparameter Tuning | Search space & hyperparameter optimization template |
| `pd.exp5(output_file, *, quiet=False)` | Evaluation & CV | Cross-validation and metric benchmarking template |
| `pd.exp6(output_file, *, quiet=False)` | Ensembling & Stacking | Multi-model ensembling and blending template |
| `pd.exp7(output_file, *, quiet=False)` | Model Compression | Quantization and pruning template |
| `pd.exp8(output_file, *, quiet=False)` | Production Benchmarking | Latency, throughput, and inference profiling template |

---

## Error Handling

`pandaaas` enforces strict validation before attempting any file writes:

- **`FileNotFoundError`**: Raised when `output_file` does not exist on disk.
  ```python
  pd.exp1("missing_file.py")
  # FileNotFoundError: Destination file 'missing_file.py' does not exist. pandaaas will not create new files; please create the destination file first.
  ```
- **`ValueError`**: Raised if:
  - The destination file does not end in `.py`.
  - The destination is a symbolic link.
  - The destination is a special device file or socket.
  - The experiment number is not between 1 and 8.
- **`IsADirectoryError`**: Raised if `output_file` points to an existing directory instead of a regular file.
- **`PermissionError`**: Propagated if filesystem write permissions are denied.
- **`TypeError`**: Raised if `output_file` is not a string or PathLike object.

---

## Security and Safety Model

- **No Code Execution**: `pandaaas` acts as a pure text generator. It does not invoke Python's `eval()`, `exec()`, or `compile(..., 'exec')`, and does not spawn child processes.
- **Explicit Target Overwriting**: Files are only overwritten when explicitly requested by a direct function invocation with an explicit `output_file` parameter.
- **No Symlink Traversal**: Symbolic link targets cannot be overwritten through `pandaaas`.

---

## Contributing and Reporting Bugs

Please review [CONTRIBUTING.md](CONTRIBUTING.md) for local setup instructions, test guidelines, and release procedures.

To report issues or request enhancements, open an issue on the project issue tracker.
