Skip to content

Writing docstrings that quelltest can read in Python

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).

What does it extract from this module?

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):

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 partBecomesExample
Raises: entrymust_raiseValueError: If amount is zero or negative.
Parameter text with a constraintboundaryamount: Must be positive (> 0).
Parameter text listing allowed valuesenum_validcurrency: One of USD, EUR, GBP.
Returns:must_returndict 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:

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.