claude-gen/fission-python/reference.md

# Fission Python Skill Reference

Detailed reference for the fission-python-skill tools.

---

## create-project.sh

Create a new Fission Python project from the standard template.

### Usage
```bash
fission-python-skill create-project <project-name> [destination-directory]
```

### Arguments
- `project-name`: Name for the new fission project (used for directories and configuration)
- `destination-directory`: Optional directory where the project should be created (defaults to current directory)

### Description
Creates a new Fission Python project by copying the template from the plugin's `template/` directory. The plugin is portable and works from any location - the template is stored relative to the plugin itself.

The template includes:
- Standard directory structure (src/, .fission/, specs/, test/, manifests/, migrates/)
- Example Python functions with fission configuration in docstrings
- Configuration files (.fission/deployment.json, etc.)
- Development setup (devcontainer, requirements, etc.)
- CI/CD workflows (.gitea/workflows/)
- build.sh script for packaging

After project creation, the script validates that:
- `src/build.sh` exists and is executable
- `.fission/deployment.json` references `./build.sh`
- `src/requirements.txt` exists and contains essential dependencies (pydantic, flask)
- `.gitea/workflows/` directory exists with at least 4 workflow files
- Python files have docstrings (excluding __init__.py)
- models.py uses pydantic.BaseModel

Validation warnings or errors are displayed to ensure the project follows best practices.

### Examples
```bash
# Create project in current directory
fission-python-skill create-project my-function

# Create project in specific directory
fission-python-skill create-project my-function ./projects/

# Create project with different name
fission-python-skill create-project data-processing-tool ./services/
```

---

## analyze-config.sh

Analyze and display Fission configuration from a project's .fission directory.

### Usage
```bash
fission-python-skill analyze-config <project-path>
```

### Arguments
- `project-path`: Path to the fission project directory (should contain .fission/ subdirectory)

### Description
Reads and parses the fission configuration files (.fission/deployment.json and related files) to provide a structured summary of:
- Environments and their resource allocation (CPU, memory, scaling)
- Packages and their build commands
- Functions and their HTTP triggers
- Secrets and ConfigMaps
- Archives and source configuration

### Output Format
The analysis is displayed in a human-readable format showing:
- Project overview
- Environment configurations
- Package details
- Function specifications
- Security configurations (secrets/configmaps)

### Examples
```bash
# Analyze current directory project
fission-python-skill analyze-config .

# Analyze specific project
fission-python-skill analyze-config ./my-fission-project

# Analyze project in parent directory
fission-python-skill analyze-config ../data-processing-service
```

---

## update-docstring.sh

Parse and update the embedded Fission configuration in Python function docstrings.

### Usage
```bash
fission-python-skill update-docstring <file-path> [function-name] [--set "<json>"] [--get] [--help]
```

### Arguments
- `file-path`: Path to the Python file containing the function
- `function-name`: Optional specific function name to target (if not provided, processes all functions with fission configuration)
- `--set "<json>"`: Set the fission configuration to the provided JSON string
- `--get`: Get/display the current fission configuration (default action if neither --set nor --get provided)
- `--help`: Show help message

### Description
This tool extracts, displays, and can modify the Fission configuration embedded in Python function docstrings. The configuration is expected to be between ```fission and ``` markers in the docstring.

The tool preserves:
- All function code outside the docstring
- Docstring content outside the fission configuration blocks
- Formatting and indentation of the existing code
- Only modifies the content between ```fission markers

### Examples
```bash
# View current fission configuration in a function
fission-python-skill update-docstring ./src/my_function.py main --get

# Update fission configuration with new JSON
fission-python-skill update-docstring ./src/my_function.py main --set '{"name": "updated-function", "http_triggers": {"updated-trigger": {"url": "/new-endpoint", "methods": ["POST"]}}}'

# Process all functions with fission configuration in a file
fission-python-skill update-docstring ./src/functions.py --get

# View help
fission-python-skill update-docstring --help
```

### Configuration Format
The fission configuration should be valid JSON representing the function's fission definition, typically including:
- `name`: Function name
- `environment`: Optional environment override
- `http_triggers`: HTTP endpoint configuration
- `schedule_triggers`: Cron-based triggers (if applicable)
- `message_queue_triggers`: Message queue triggers (if applicable)

### Error Handling
- Returns error if file doesn't exist
- Returns error if function not found (when specified)
- Returns error if no fission configuration found in function docstring
- Returns error if provided JSON is invalid (when using --set)
- Preserves original file on error (no partial writes)

---

## Installation

The fission-python-skill is automatically available when the fission-plugin is installed. To use the tools directly:

1. Navigate to the plugin directory and run tools directly:
   ```bash
   cd /path/to/fission-python-skill
   ./create-project.sh my-project
   ```

2. Or add the plugin directory to your PATH:
   ```bash
   export PATH="$PATH:/path/to/fission-python-skill"
   fission-python-skill create-project my-project
   ```

The plugin is portable and does not require any hardcoded paths - it will locate its template relative to its own location.

---

## Template Source

The project template is sourced from: `fission-python-skill/template/` (relative to the plugin location).

When creating new projects, the following files/directories are excluded from copying:
- .git/
- __pycache__/
- *.pyc
- .env
- test/ (test files are copied but may need project-specific updates)

The plugin is fully portable - it uses relative paths based on the script location, so it can be moved to different directories or systems without breaking.