# Writing docstrings that quelltest can read in Python

> Which docstring sections and Pydantic constraints the Python quelltest readers turn into requirements, with the real extraction output for a sample module.

Canonical page: https://quelltest.com/docs/guides/docstrings

The Python package reads requirements out of docstrings and Pydantic models, then checks which ones have a test. The more precisely you write `Raises:`, parameter constraints and `Literal` types, the more requirements it can extract and track. These readers feed `quell ci`, `quell prove`, the Python SDK and the MCP tool `find_edge_cases`; `quell find` reads guard clauses instead (see [how it works](https://quelltest.com/docs/how-it-works.md)).

## What does it extract from this module?

```python
from typing import Literal
from pydantic import BaseModel, Field

class Payment(BaseModel):
    amount: float = Field(gt=0)
    currency: Literal["USD", "EUR", "GBP"]
    note: str = Field(min_length=1, max_length=500)

def process_payment(amount: float, currency: str) -> dict:
    """Process a payment.

    Args:
        amount: Must be positive (> 0).
        currency: One of USD, EUR, GBP.

    Returns:
        dict with transaction_id.

    Raises:
        ValueError: If amount is zero or negative.
        ValueError: If currency is not supported.
    """
```

Running the SDK on it (`Quell(project_root=Path(".")).check(Path("src/m.py"))`) returns these requirements, in this form (kind, function, description, source):

```text
must_raise | process_payment | raises ValueError when If amount is zero or negative.   | docstring
must_raise | process_payment | raises ValueError when If currency is not supported.    | docstring
boundary   | process_payment | Must be positive                                       | docstring
enum_valid | process_payment | must be one of ['USD', 'EUR', 'GBP']                    | docstring
must_return| process_payment | returns dict with transaction_id.                      | docstring
boundary   | Payment         | Payment.amount must satisfy gt=0                       | type
enum_valid | Payment         | Payment.currency must be one of ['USD', 'EUR', 'GBP']  | type
boundary   | Payment         | Payment.note must satisfy min_length=1                 | type
boundary   | Payment         | Payment.note must satisfy max_length=500               | type
```

Nine requirements, none yet covered, so the score is 0.0.

## Which docstring parts count?

| Docstring part | Becomes | Example |
| --- | --- | --- |
| `Raises:` entry | `must_raise` | `ValueError: If amount is zero or negative.` |
| Parameter text with a constraint | `boundary` | `amount: Must be positive (> 0).` |
| Parameter text listing allowed values | `enum_valid` | `currency: One of USD, EUR, GBP.` |
| `Returns:` | `must_return` | `dict with transaction_id.` |

Google, NumPy and RST styles are supported. Prose that the structured parsers cannot read falls back to an LLM when one is configured.

## How do I write `Raises:` so it is useful?

One entry per condition, with the exception type and a specific condition:

```python
def process_payment(amount: float, currency: str) -> dict:
    """Process a payment.

    Raises:
        ValueError: If amount is zero or negative.
        ValueError: If currency is not a supported 3-letter code.
        PermissionError: If the current user may not make payments.
    """
```

`ValueError: If amount is zero or negative.` is a better requirement than `ValueError: If amount is invalid.` because the test that is generated and the violation that is injected can target the condition.

## Which Pydantic and type constraints are read?

`Field(gt=..., ge=..., lt=..., le=..., min_length=..., max_length=..., min_items=..., max_items=...)`, `Literal[...]` values and `Annotated[int, Field(ge=18)]`. You do not need to repeat them in docstrings.

## How does this relate to guard clauses?

`quell find` reads the guard clauses themselves (`if amount <= 0: raise ValueError(...)`), so the docstring is not needed there. Keeping the docstring and the guard in sync gives both readers the same requirement. See [constraint kinds](https://quelltest.com/docs/reference/constraint-kinds.md).
