Pipelex Development Standards

This skill provides comprehensive development standards and workflow practices for Pipelex, a declarative language for composable AI workflows.

Essential Commands

Code Quality and Linting

Always lint after making changes:

```bash

make check

```

This runs:

Pyright: Static type checking

Ruff: Fast Python linter

Mypy: Static type checker

Fix all reported issues before proceeding.

Testing

Run tests after code changes:

```bash

make test-xdist

```

For detailed error output:

```bash

make test-with-prints

```

Run specific tests:

```bash

make tp TEST=TestClassName

make tp TEST=test_function_name

```

Rerun only failed tests:

```bash

make tp TEST=LF

```

Virtual Environment Management

**CRITICAL**: Always activate the Python virtual environment before running commands:

```bash

Standard activation

source .venv/bin/activate # macOS/Linux

.venv\Scripts\activate # Windows

Or use direct path

.venv/bin/python -m pytest

.venv/bin/pipelex validate all

```

Python Coding Standards

Variables and Loops

Minimum 3-character variable names

Use descriptive loop indexes: `index_foobar`

Use `for key in the_dict` not `for key in the_dict.keys()`

Declare typed variables without default values when appropriate:

```python

pipe_code: str # Good - unbound until assigned

```

Enums and Pattern Matching

Inherit from `StrEnum` for string enums

Always use match/case for enum comparisons

Never add `case _:` default cases

Import from pipelex.types:

```python

from pipelex.types import StrEnum

```

Imports and Dependencies

Import all libraries at the top of files

Use direct imports from pipelex:

```python

from pipelex import log, pretty_print

from pipelex.types import Self, StrEnum

```

Type Hints

Type all function parameters and returns

Use lowercase built-in types: `dict[]`, `list[]`, `tuple[]`

Use `BaseModel` with Pydantic v2 standards

For list fields in BaseModels:

```python

from pipelex.tools.typing.pydantic_utils import empty_list_factory_of

numbers: list[int] = Field(default_factory=empty_list_factory_of(int))

```

Error Handling

Catch specific exceptions, never generic `Exception`

Add context when catching exceptions

Always use `from exc` in raise statements:

```python

try:

self.models_manager.setup()

except RoutingProfileLibraryNotFoundError as exc:

msg = "Library not found, run `pipelex init config`"

raise PipelexSetupError(msg) from exc

```

Testing Standards

Test Structure

Use pytest-mock, NEVER unittest.mock

Organize tests in appropriate directories:

- `tests/unit/` - isolated function/class tests

- `tests/integration/` - component interaction tests

- `tests/e2e/` - complete workflow tests

- `tests/test_pipelines/` - pipeline definitions

Test Organization

Always use Test classes (one per module)

Apply appropriate markers:

```python

@pytest.mark.llm

@pytest.mark.inference

@pytest.mark.asyncio(loop_scope="class")

class TestFooBar:

@pytest.mark.parametrize("topic, test_case", [

TestCases.CASE_1,

TestCases.CASE_2,

])

async def test_pipe_processing(self, topic, test_case):

# Test implementation

```

Available Markers

`llm`: Uses LLM for text/object generation

`img_gen`: Uses image generation AI

`extract`: Uses text/image extraction

`inference`: Uses LLM or image generation

`gha_disabled`: Won't run on GitHub Actions

Test Data

Create `test_data.py` files in test directories

Use ClassVar for default mutable values

Organize data in classes for tidiness

Test-Driven Development

1. **Write Test First** - Define expected behavior

2. **Write Minimal Code** - Just enough to pass the test

3. **Run Quality Checks** - `make check` for linting

4. **Validate Tests** - Ensure all tests pass

Documentation Standards

Use Material for MkDocs compatible markdown:

Always add blank lines before lists

Follow Material for MkDocs best practices

Include docstrings for functions and classes:

```python

def process_image(image_path: str, size: tuple[int, int]) -> bytes:

"""Process and resize an image.

Args:

image_path: Path to the source image

size: Tuple of (width, height) for resizing

Returns:

Processed image as bytes

"""

```

This skill ensures consistent, high-quality development practices across the Pipelex codebase with proper testing, linting, and documentation standards.

Pipelex Development Standards

Pipelex Development Standards

Essential Commands

Code Quality and Linting

Testing

Virtual Environment Management

Standard activation

Or use direct path

Python Coding Standards

Variables and Loops

Enums and Pattern Matching

Imports and Dependencies

Type Hints

Error Handling

Testing Standards

Test Structure

Test Organization

Available Markers

Test Data

Test-Driven Development

Documentation Standards

Reviews (0)