Adding Features¶

How to add new functionality to Sutras.

New CLI Command¶

Add to src/sutras/cli/main.py:

@cli.command()
@click.argument("name")
@click.option("--flag", help="Description")
def command(name: str, flag: bool) -> None:
    """Command description."""
    try:
        # Implementation
        click.echo(click.style("Success", fg="green"))
    except Exception as e:
        click.echo(click.style(f"Error: {e}", fg="red"), err=True)
        raise click.Abort()

CLI Checklist¶

[ ] Add command with @cli.command()
[ ] Use type hints for all parameters
[ ] Add docstring (shown in --help)
[ ] Handle errors with colored output
[ ] Add tests for the command
[ ] Document in CLI reference

New Core Feature¶

Create module in src/sutras/core/
Include type hints and docstrings
Export from __init__.py if public
Add tests in tests/
Update docs as needed

Example Module¶

# src/sutras/core/myfeature.py
"""My feature module."""

from dataclasses import dataclass


@dataclass
class MyFeature:
    """Represents my feature.

    Args:
        name: Feature name
        enabled: Whether feature is enabled
    """

    name: str
    enabled: bool = True

    def process(self) -> str:
        """Process the feature.

        Returns:
            Processed result string
        """
        if not self.enabled:
            raise ValueError("Feature is disabled")
        return f"Processed: {self.name}"

Export Public API¶

In src/sutras/core/__init__.py:

from sutras.core.myfeature import MyFeature

__all__ = [
    "MyFeature",
    # ... other exports
]

Testing New Features¶

# tests/test_myfeature.py
import pytest
from sutras.core.myfeature import MyFeature


def test_process_enabled():
    """Test processing when enabled."""
    feature = MyFeature(name="test")
    result = feature.process()
    assert result == "Processed: test"


def test_process_disabled_raises():
    """Test that disabled feature raises."""
    feature = MyFeature(name="test", enabled=False)
    with pytest.raises(ValueError):
        feature.process()

Documentation¶

For significant features:

Update relevant docs pages
Add examples if applicable
Update CHANGELOG.md

Pull Requests