Skip to main content
Version: v5

Function Examples

Every command should carry at least one working example. Examples are declared in the examples argument of @router.command, stored in the route's OpenAPI metadata, and written into the Examples section of the generated Python docstring as >>> lines. The generated reference pages and the repository's integration-test generators read them too.

from openbb_core.app.model.example import APIEx, PythonEx

APIEx​

APIEx describes a call as a dictionary of parameters, which keeps it language-neutral: the same example renders as a Python call and as REST query parameters. The openbb-famafrench router declares its factors examples like this:

@router.command(
    model="FamaFrenchFactors",
    methods=["GET"],
    examples=[
        APIEx(
            description="Fama-French 3-factors data for America, default is monthly.",
            parameters={
                "provider": "famafrench",
            },
        ),
        APIEx(
            description="Fama-French 5-factors data for Europe.",
            parameters={
                "provider": "famafrench",
                "region": "europe",
                "factor": "5_factors",
            },
        ),
    ],
)
async def factors(
    cc: CommandContext,
    provider_choices: ProviderChoices,
    standard_params: StandardParams,
    extra_params: ExtraParams,
) -> OBBject:
    """Fama-French factors."""
    return await OBBject.from_query(Query(**locals()))

In the docstring the second example becomes obb.famafrench.factors(provider='famafrench', region='europe', factor='5_factors'), preceded by its description as a comment line.

Parameter values can be strings, numbers, booleans, lists of strings, or lists of dictionaries. provider, when present, must be a string. description is optional, but it is required once an example has more than three parameters besides provider; the model raises a validation error otherwise. When the provider named in an example is not installed, that example is left out of the docstring and the OpenAPI schema.

POST commands that take a data list can use APIEx.mock_data("timeseries") for a small OHLCV sample or APIEx.mock_data("panel") for multi-index panel data, instead of pasting rows:

APIEx(parameters={"target": "close", "data": APIEx.mock_data("timeseries")})

PythonEx​

PythonEx holds free-form code for examples that need more than one call. description is required, and each item of code is one line.

PythonEx(
    description="50-day simple moving average of SPY closing prices from Cboe.",
    code=[
        "data = obb.cboe.equity.historical(symbol='SPY', provider='cboe').results",
        "sma = obb.technical.sma(data=data, length=50)",
    ],
)

PythonEx examples are always kept, whatever is installed, so write them against commands that users of your extension will have. Rebuild with openbb-build to see changed examples in the generated docstrings.

On this page