Extensions API Reference

API documentation for the extension system.

BaseExtension

The abstract base class for all extensions.

gtext.extensions.base.BaseExtension

Bases: ABC

Abstract base class for gtext extensions.

All extensions must inherit from this class and implement the process method.

Attributes:

Name	Type	Description
`name`	`str`	Unique identifier for the extension

Example

class MyExtension(BaseExtension): ... name = "my-extension" ... ... def process(self, content: str, context: dict) -> str: ... return content.upper()

process `abstractmethod`

process(content: str, context: Dict) -> str

Process content and return transformed result.

Parameters:

Name	Type	Description	Default
`content`	`str`	The text content to process	required
`context`	`Dict`	Context dictionary with metadata (e.g., input_path)	required

Returns:

Type	Description
`str`	The transformed content

Source code in gtext/extensions/base.py

@abstractmethod
def process(self, content: str, context: Dict) -> str:
    """Process content and return transformed result.

    Args:
        content: The text content to process
        context: Context dictionary with metadata (e.g., input_path)

    Returns:
        The transformed content

    Raises:
        Any extension-specific exceptions
    """
    pass

IncludeExtension

The built-in extension for file includes, CLI output, and glob patterns.

gtext.extensions.include.IncludeExtension

Bases: BaseExtension

Extension that processes ```include blocks.

Supports multiple protocols: - static: Static files (default if no protocol specified) - cli: Execute shell commands - glob: Multiple files via glob patterns

Supports modifiers (prefix with :modifier:): - expand: Recursively process the included content

Syntax

protocol: content # Basic :expand:protocol: content # With expand modifier

Examples:

static: header.md                      # Include file as-is
:expand:static: template.md.gtext      # Include and expand recursively
cli: python get_stats.py               # Execute command
:expand:cli: python generate_doc.py    # Execute and expand output
glob: sections/*.md                    # Include multiple files
footer.md                              # Implicit static:

Backward compatibility: Lines without protocol are treated as static: paths.

process

process(content: str, context: Dict) -> str

Process all ```include blocks in the content.

Parameters:

Name	Type	Description	Default
`content`	`str`	The text content to process	required
`context`	`Dict`	Context dict (should contain 'input_path' for relative path resolution)	required

Returns:

Type	Description
`str`	Content with all ```include blocks replaced by their resolved content

Source code in gtext/extensions/include.py

def process(self, content: str, context: Dict) -> str:
    """Process all ```include blocks in the content.

    Args:
        content: The text content to process
        context: Context dict (should contain 'input_path' for relative path resolution)

    Returns:
        Content with all ```include blocks replaced by their resolved content
    """
    # Initialize depth tracking if not present
    if "include_depth" not in context:
        context["include_depth"] = 0

    def replace_include(match):
        include_block = match.group(1).strip()
        return self._resolve_include_block(include_block, context)

    return self.INCLUDE_PATTERN.sub(replace_include, content)

Creating Custom Extensions

All extensions must inherit from BaseExtension and implement the process() method.

Minimal Extension

from gtext.extensions import BaseExtension

class MyExtension(BaseExtension):
    name = "my-extension"

    def process(self, content: str, context: dict) -> str:
        # Your transformation logic
        return content.upper()

Configurable Extension

from gtext.extensions import BaseExtension

class ConfigurableExtension(BaseExtension):
    name = "configurable"

    def __init__(self, option1: str = "default"):
        self.option1 = option1

    def process(self, content: str, context: dict) -> str:
        # Use self.option1 in processing
        return content

Context-Aware Extension

from pathlib import Path
from gtext.extensions import BaseExtension

class ContextExtension(BaseExtension):
    name = "context-aware"

    def process(self, content: str, context: dict) -> str:
        # Read from context
        input_path = context.get("input_path")

        # Write to context
        context["processed"] = True

        return content

Usage

Register Extension

from gtext import TextProcessor
from my_extension import MyExtension

processor = TextProcessor(extensions=[MyExtension()])

Multiple Extensions

processor = TextProcessor(extensions=[
    Extension1(),
    Extension2(),
    Extension3(),
])

Extensions are applied in the order they are registered.