ref: up
This commit is contained in:
Duc Nguyen
185
fission-python/reference.md
Normal file
185
fission-python/reference.md
Normal file
@@ -0,0 +1,185 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user