Metadata-Version: 2.4
Name: nbtemplate-py
Version: 0.1.3
Summary: CLI tool to manage and populate Jupyter notebook templates
Home-page: https://github.com/MakPr016/nbtemplate
Author: MakPr016
Author-email: makcode31sk@gmail.com
License: MIT
Project-URL: Bug Reports, https://github.com/MakPr016/nbtemplate/issues
Project-URL: Source, https://github.com/MakPr016/nbtemplate
Project-URL: Documentation, https://github.com/MakPr016/nbtemplate#readme
Keywords: jupyter notebook template colab automation
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=7.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: project-url
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# NBTemplate

**A CLI tool to manage and auto-fill Jupyter Notebook templates** - Create reusable notebook templates and quickly generate new notebooks with your custom code blocks.

## Features

- **Create Templates** - Mark code blocks in your notebooks as template placeholders  
- **Interactive CLI** - Get prompted for each template block when creating notebooks  
- **Easy Distribution** - Share templates as `.ipynb` files  
- **Flexible Syntax** - Use `###TEMPLATE:block_name###` or `{{block_name}}` to mark blocks  
- **Customizable** - Define block descriptions in your templates  
- **Pre-loaded Templates** - Comes with built-in example templates  
- **Template Management** - Organize templates in folders, add new ones easily  

## Installation

```bash
pip install nbtemplate-py
```

## Quick Start

### 1. See available templates

```bash
nbtemplate list
```

You'll see bundled templates like `ml_template` that come with the package!

### 2. Create a notebook from a template

```bash
nbtemplate create --output my_notebook.ipynb
```

The CLI will:

1. Show available templates (bundled + your custom ones)
2. Let you select one
3. Prompt for each template block
4. Create and save your notebook

### 3. Add your own templates

Create a Jupyter notebook with template markers and save it:

```bash
nbtemplate add /path/to/your/template.ipynb
```

Your custom templates are saved to: `~/.nbtemplate/templates/`

#### Example template structure

**Cell 1 - Configuration:**

```python
TEMPLATE_CONFIG = {
    "imports": "Import libraries and dependencies",
    "data_loading": "Load and explore your dataset",
    "analysis": "Main analysis code",
    "visualization": "Create plots and visualizations",
}
```

**Cell 2 - Imports Block:**

```python
###TEMPLATE:imports###
# Your imports will be inserted here
```

**Cell 3 - Data Loading Block:**

```python
###TEMPLATE:data_loading###
# Your data loading code will go here
```

**Cell 4 - Analysis Block:**

```python
###TEMPLATE:analysis###
# Your analysis code will go here
```

**Cell 5 - Visualization Block:**

```python
###TEMPLATE:visualization###
# Your visualization code will go here
```

Save as `my_template.ipynb` and add it:

```bash
nbtemplate add my_template.ipynb
```

## Commands

### `nbtemplate list`

List all available templates (bundled + user templates).

```bash
nbtemplate list
nbtemplate list --templates-dir ./my_templates
```

### `nbtemplate create`

Create a new notebook by filling a template interactively.

```bash
nbtemplate create
nbtemplate create --output my_notebook.ipynb
nbtemplate create --templates-dir ./my_templates
```

**Options:**

- `-o, --output`: Output notebook path (default: `notebook.ipynb`)
- `--templates-dir`: Use a custom templates directory

### `nbtemplate add`

Add a template notebook to your templates directory.

```bash
nbtemplate add path/to/template.ipynb
nbtemplate add path/to/template.ipynb --templates-dir ./my_templates
```

### `nbtemplate init`

Initialize a new templates directory with an example template.

```bash
nbtemplate init
nbtemplate init --templates-dir ./my_templates
```

## Template Organization

### Bundled Templates

When you install nbtemplate, you get built-in templates:

- `ml_template` - Machine learning workflow with 6 stages

These are included in the package and work out of the box!

### User Templates

Your custom templates are stored in: `~/.nbtemplate/templates/`

Just add `.ipynb` files there and they'll automatically appear in `nbtemplate list`!

**Folder structure:**

```
~/.nbtemplate/
└── templates/
    ├── data_analysis.ipynb
    ├── research_notebook.ipynb
    └── my_custom_template.ipynb
```

## Quick Start

### 1. Initialize templates directory

```bash
nbtemplate init
```

This creates `~/.nbtemplate/templates/` with an example template.

### 2. Create your first template

Create a Jupyter notebook with template markers:

```python
# Cell 1 - Configuration
TEMPLATE_CONFIG = {
    "imports": "Import libraries and dependencies",
    "data_loading": "Load and explore your dataset",
    "analysis": "Main analysis code",
    "visualization": "Create plots and visualizations",
}

# Cell 2 - Imports block
###TEMPLATE:imports###
# Your imports will go here

# Cell 3 - Data Loading block
###TEMPLATE:data_loading###
# Your data loading code will go here

# Cell 4 - Analysis block
###TEMPLATE:analysis###
# Your analysis code will go here

# Cell 5 - Visualization block
###TEMPLATE:visualization###
# Your visualization code will go here
```

Save as `my_template.ipynb` and add it:

```bash
nbtemplate add my_template.ipynb
```

### 3. Create notebooks from templates

```bash
nbtemplate create
```

The CLI will:

1. Show available templates
2. Let you select one
3. Prompt for each template block
4. Create and save your notebook

Specify output path:

```bash
nbtemplate create --output my_analysis.ipynb
```

## Commands

### `nbtemplate init`

Initialize a new templates directory with an example template.

```bash
nbtemplate init
nbtemplate init --templates-dir ./my_templates
```

### `nbtemplate list`

List all available templates.

```bash
nbtemplate list
nbtemplate list --templates-dir ./my_templates
```

### `nbtemplate add`

Add a template notebook to the templates directory.

```bash
nbtemplate add path/to/template.ipynb
nbtemplate add path/to/template.ipynb --templates-dir ./my_templates
```

### `nbtemplate create`

Create a new notebook by filling a template interactively.

```bash
nbtemplate create
nbtemplate create --output my_notebook.ipynb
nbtemplate create --templates-dir ./my_templates
```

## Template Syntax

Mark placeholder blocks in your template using either syntax:

### Syntax 1: Comment markers

```python
###TEMPLATE:block_name###
# placeholder code
```

### Syntax 2: Mustache-style

```python
{{block_name}}
# placeholder code
```

## Configuration

### Custom templates directory

Set the `NBTEMPLATE_DIR` environment variable:

```bash
# Linux/Mac
export NBTEMPLATE_DIR=/path/to/my/templates
nbtemplate create

# Windows (PowerShell)
$env:NBTEMPLATE_DIR="C:\path\to\templates"
nbtemplate create
```

Or use `--templates-dir` with any command:

```bash
nbtemplate create --templates-dir /path/to/my/templates
```

### Template block descriptions

Add a `TEMPLATE_CONFIG` dict in the first code cell to provide descriptions:

```python
TEMPLATE_CONFIG = {
    "imports": "Import necessary libraries",
    "data_loading": "Load and explore data",
    "preprocessing": "Data cleaning and preprocessing",
}
```

Descriptions are shown when filling templates for context.

## Example Workflows

### Machine Learning Pipeline

```python
TEMPLATE_CONFIG = {
    'imports': 'Import ML libraries (pandas, scikit-learn, numpy)',
    'data_loading': 'Load and explore your dataset',
    'preprocessing': 'Data preprocessing and feature engineering',
    'model_training': 'Train your machine learning model',
    'evaluation': 'Evaluate model performance with metrics',
    'visualization': 'Create visualizations and plots',
}
```

### Data Analysis

```python
TEMPLATE_CONFIG = {
    "imports": "Import pandas, numpy, matplotlib",
    "data_loading": "Load your CSV or dataset",
    "exploration": "Exploratory data analysis",
    "insights": "Key findings and conclusions",
}
```

### Research Notebook

```python
TEMPLATE_CONFIG = {
    "literature": "Related work and background",
    "hypothesis": "Research hypothesis and approach",
    "implementation": "Implementation of the approach",
    "experiments": "Experimental setup and execution",
    "results": "Results and analysis",
    "conclusion": "Conclusions and future work",
}
```

## Google Colab Support

NBTemplate works great with Google Colab!

```bash
# In Colab cell
!pip install nbtemplate
!nbtemplate init
!nbtemplate create --output my_notebook.ipynb
```

Or download templates from GitHub:

```bash
!nbtemplate add https://raw.githubusercontent.com/user/repo/main/templates/ml_template.ipynb
!nbtemplate create
```

## Sharing Templates

### Share via GitHub

1. Create a repository for your templates
2. Add your `.ipynb` template files
3. Share the repository URL
4. Others can clone and add templates

### Use Cases

- **Data Analysis** - Template with data loading, EDA, and visualization blocks  
- **Machine Learning** - Standardized ML pipeline (preprocessing, training, evaluation)  
- **Reports** - Consistent report structure across projects  
- **Experiments** - Reproducible experiment setup  
- **Education** - Structured assignment templates for students  
- **Team Projects** - Standardized notebooks for team collaboration  

## Python API

You can also use NBTemplate programmatically:

```python
from nbtemplate.template import TemplateManager, TemplateBlockCollector

# Load templates
tm = TemplateManager("~/.nbtemplate/templates")
templates = tm.get_available_templates()

# Fill template
blocks = {
    "imports": "import pandas as pd",
    "data_loading": "df = pd.read_csv('data.csv')",
    "analysis": "print(df.describe())",
}

notebook = tm.fill_template("my_template", blocks)
tm.save_notebook(notebook, "output.ipynb")
```

## Project Structure

```
nbtemplate/
├── __init__.py          # Package metadata
├── template.py          # Core logic (TemplateManager, TemplateBlockCollector)
├── cli.py              # CLI commands
├── templates/           # Built-in templates
│   ├── ml_template.ipynb   # Example ML template
│   └── __init__.py
├── setup.py            # Package configuration
├── README.md           # This file
└── LICENSE             # MIT License
```

## Troubleshooting

### Templates not found

```bash
# Check templates directory
nbtemplate list

# Initialize templates
nbtemplate init

# Set custom directory
export NBTEMPLATE_DIR=/your/path
nbtemplate list
```

### Template block not recognized

Check that block markers use the correct syntax:

- `###TEMPLATE:block_name###` (triple hashes)
- `{{block_name}}` (double braces)

Block names must be alphanumeric with underscores.

## Requirements

- Python 3.7+
- click (installed automatically)

## License

MIT License - see LICENSE file for details

## Contributing

Contributions welcome! Please feel free to:

- Report issues
- Submit pull requests
- Share template ideas
- Suggest improvements

Visit the repository: <https://github.com/MakPr016/nbtemplate>

## Support

For issues, questions, or feature requests, please visit:
<https://github.com/MakPr016/nbtemplate/issues>

---

Made with ❤️ by MakPr016
