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

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

# 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

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

# 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

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

# 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:

   cd /path/to/fission-python-skill
   ./create-project.sh my-project
   

2. Or add the plugin directory to your PATH:

   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.