Core API Reference¶

Complete auto-generated reference for every public module in steplib.core.

Public API¶

The top-level steplib package re-exports the most commonly used symbols for convenience. Each is documented in its respective section below.

steplib.__version__ = '1.4.1.dev1'¶

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to ‘strict’.

Decorators¶

The @step decorator and related helpers.

The decorator stores StepInfo metadata on the decorated function. When multiple decorators are stacked on the same function, each call appends a new StepInfo entry to fn.__steplib_steps__.

steplib.core.decorators.get_step_infos(fn)[source]¶

Return all StepInfo entries attached to a decorated function.

Parameters:: fn (Callable[..., Any]) – A function decorated with @step.
Return type:: list[StepInfo]
Returns:: A list of StepInfo objects (empty if the function is not a steplib step).

steplib.core.decorators.step(pattern, *, category, backend=None, description=None, parameters=None, example=None, tags=None, version=None, deprecated=False, i18n=None, requires=None)[source]¶

Attach StepInfo metadata to a step function.

Can be stacked to register multiple patterns (e.g. for i18n or alternative backends) on the same implementation function.

Parameters:

pattern (str) – The behave matching pattern (e.g. "I send a {method} request to {url}").
category (str) – Module/domain category (e.g. "api", "web").
backend (str | None) – Underlying technology (e.g. "httpx", "requests").
description (str | None) – Human-readable description; defaults to the function docstring.
parameters (list[Param] | None) – Typed parameter descriptors.
example (str | None) – Example usage in Gherkin.
tags (list[str] | None) – Tags for grouping/filtering in the CLI.
version (str | None) – Semver of the step.
deprecated (bool | str) – True, a deprecation message, or False.
i18n (dict[str, str] | None) – Translations of the pattern keyed by language code.
requires (list[str] | None) – Context attributes the step needs (e.g. ["steplib.api.client"]).

Return type:

Callable[[Callable[..., Any]], Callable[..., Any]]

Returns:

A decorator that records the metadata and returns the function unchanged.

Metadata¶

Step metadata dataclass.

class steplib.core.metadata.StepInfo(pattern, category, func, backend=None, description=None, parameters=<factory>, example=None, tags=<factory>, version=None, deprecated=False, i18n=<factory>, requires=<factory>)[source]¶

Bases: object

Immutable metadata describing a single step registration.

A function decorated with @step may produce multiple StepInfo entries (one per stacked decorator call). Each entry is expanded into one or more patterns via i18n translations.

backend: str | None¶

category: str¶

deprecated: bool | str¶

description: str | None¶

example: str | None¶

func: Callable[..., Any]¶

i18n: dict[str, str]¶

property is_deprecated: bool¶: Whether this step is marked as deprecated.

property module: str¶: Dotted module path of the step function.

parameters: list[Param]¶

pattern: str¶

property qualified_name: str¶: Fully qualified function name (module.qualname).

requires: list[str]¶

tags: list[str]¶

version: str | None¶

Parameters¶

Parameter types and the Param dataclass for step metadata.

class steplib.core.params.Param(name, type=<class 'str'>, required=False, default=None, description=None, choices=<factory>)[source]

Bases: object

Describes a single step parameter extracted from the pattern.

name: Placeholder name as it appears in the pattern (e.g. "method").

type: Python type or registered type name (e.g. int, "Json").

required: Whether the parameter must be present.

default: Default value when the parameter is not in the pattern.

description: Human-readable description of the parameter.

choices: Allowed values after conversion.

choices: list[Any]

default: Any

description: str | None

name: str

required: bool

type: type[Any] | str

class steplib.core.params.TypeRegistry[source]

Bases: object

Registry of custom types registered via register_type.

Encapsulates mutable state that was previously a module-level dict, avoiding global mutable state.

get(name)[source]

Return the registered type for name, or None if not registered.

Return type:: type[Any] | None

register(name, py_type)[source]

Parameters:

name (str) – The type name to use in patterns.
py_type (type[Any]) – The Python type the converter returns.

Return type:

None

resolve(type_ref)[source]

Resolve a type reference (type object or name) to a Python type.

Parameters:: type_ref (type[Any] | str) – A type object or a registered type name.
Return type:: type[Any]
Returns:: The resolved Python type, falling back to str for unknown names.

steplib.core.params.register_type(name, py_type)[source]

Delegates to the default TypeRegistry instance.

Parameters:

name (str) – The type name to use in patterns.
py_type (type[Any]) – The Python type the converter returns.

Return type:

None

steplib.core.params.resolve_type(type_ref)[source]

Resolve a type reference (type object or name) to a Python type.

Delegates to the default TypeRegistry instance.

Parameters:: type_ref (type[Any] | str) – A type object or a registered type name.
Return type:: type[Any]
Returns:: The resolved Python type, falling back to str for unknown names.

Registry¶

Central registry for step metadata and behave integration.

class steplib.core.registry.BehaveLikeRegistry(*args, **kwargs)[source]¶

Bases: Protocol

Minimal protocol for behave’s step registration API.

step(pattern)[source]¶

Parameters:: pattern (str) – The behave matching pattern.
Return type:: Callable[[Callable[..., Any]], Callable[..., Any]]
Returns:: A decorator that attaches the function to the pattern.

class steplib.core.registry.StepRegistry(auto_register_behave=True)[source]¶

Bases: object

Stores StepInfo entries and optionally registers them with behave.

Parameters:: auto_register_behave (bool) – When True, each pattern is also registered with behave’s global step registry via behave.step.

add(fn)[source]¶

Extracts StepInfo entries from fn.__steplib_steps__, expands i18n translations, checks for duplicates, and optionally registers each pattern with behave.

Parameters:

fn (Callable[..., Any]) – A function decorated with @step.

Raises:

StepContractError – If fn has no steplib step metadata.
DuplicateStepError – If a pattern is already registered for the same backend.

Return type:

None

available_backends(category=None)[source]¶

Return the set of backends present in the registry.

Parameters:: category (str | None) – Optional category to narrow the search.
Return type:: set[str]
Returns:: A set of backend names.

available_categories()[source]¶

Return the set of categories present in the registry.

Return type:: set[str]
Returns:: A set of category names.

filter(category=None, backend=None, tag=None)[source]¶

Return steps matching the given filters (all optional, AND-combined).

Parameters:

category (str | None) – Filter by category (e.g. "api").
backend (str | None) – Filter by backend (e.g. "httpx").
tag (str | None) – Filter by tag.

Return type:

list[StepInfo]

Returns:

A list of StepInfo entries matching all provided filters.

find(pattern, backend=None)[source]¶

Alias for get().

Parameters:

pattern (str) – The step pattern to look up.
backend (str | None) – Optional backend to narrow the search.

Return type:

StepInfo | None

Returns:

The matching StepInfo or None if not found.

get(pattern, backend=None)[source]¶

Return the StepInfo for pattern (optionally filtered by backend).

When backend is None, returns the first match regardless of backend.

Parameters:

pattern (str) – The step pattern to look up.
backend (str | None) – Optional backend to narrow the search.

Return type:

StepInfo | None

Returns:

The matching StepInfo or None if not found.

replace_steps(kept)[source]¶

Replace the registry’s contents with kept steps only.

Used by discovery filters to narrow the registry after loading. Rebuilds the internal pattern index from the kept steps.

Parameters:: kept (list[StepInfo]) – The StepInfo entries to keep.
Return type:: None

property steps: list[StepInfo]¶: All registered StepInfo entries (unfiltered).

Discovery¶

Discovery and loading of steplib plugins via entry points.

steplib.core.discovery.autoload(context, categories=None, backends=None)[source]¶

Load all installed steplib plugins and attach state to context.

Parameters:

context (Any) – The behave context object.
categories (list[str] | None) – Optional list of categories to keep (e.g. ["api"]). When None, all categories are loaded.
backends (dict[str, str] | None) – Optional mapping of category → backend to keep (e.g. {"api": "httpx"}). When None, all backends are loaded.

Return type:

SteplibState

Returns:

A SteplibState holding the filtered registry.

steplib.core.discovery.get_registry()[source]¶

Build a registry from all installed plugins without behave registration.

Used by the CLI to query step metadata outside of a behave run.

Return type:: StepRegistry

steplib.core.discovery.load(context, *modules)[source]¶

Load specific step modules by dotted path and attach state to context.

Parameters:

context (Any) – The behave context object.
*modules (str) – Dotted module paths to import (e.g. "steplib.modules.api.steps"). Each module must expose a register(registry) function.

Return type:

SteplibState

Returns:

A SteplibState holding the registry.

State¶

Per-run and per-scenario state attached to behave’s context.

class steplib.core.state.BehaveContext(*args, **kwargs)[source]

Bases: Protocol

Minimal protocol for behave’s context object.

config: The behave configuration object.

steplib: The SteplibState attached by steplib’s autoload/load.

config: Any

steplib: Any

class steplib.core.state.SteplibState(context, registry)[source]

Bases: object

Holds the steplib state attached to context.steplib.

Modules set their own namespaces as attributes on this object (e.g. state.api = ApiContext(...)).

Parameters:

context (Any) – The behave context object.
registry (StepRegistry) – The StepRegistry populated during autoload/load.

cleanup()[source]

Close resources after a scenario.

Called from after_scenario. Iterates over all module-level attributes (non-underscore) and calls cleanup() if available.

Return type:: None

property context: Any: The behave context.

property registry: StepRegistry: The step registry.

reset()[source]

Reset per-scenario state.

Called from before_scenario. Iterates over all module-level attributes (non-underscore) and calls reset() if available.

Return type:: None

i18n¶

Internationalisation helpers for step patterns.

The design mandates that all patterns (base + translations) are registered with behave. No language filtering is performed at registration time; behave matches the pattern that corresponds to the text in the feature file.

steplib.core.i18n.SUPPORTED_LANGS: frozenset[str] = frozenset({'en', 'es', 'pt'})¶: Language codes supported by steplib’s i18n system.

steplib.core.i18n.expand_patterns(info)[source]¶

Expand a StepInfo into (lang, pattern) pairs.

The base pattern is tagged "en". Each entry in info.i18n adds a translated pattern tagged with its language code.

Parameters:: info (StepInfo) – The step metadata to expand.
Return type:: list[tuple[str, str]]
Returns:: A list of (language_code, pattern_text) tuples, starting with the base English pattern.

steplib.core.i18n.extract_placeholders(pattern)[source]¶

Return the ordered list of placeholder names in a pattern.

Parameters:: pattern (str) – A behave step pattern containing {name} or {name:Type} placeholders.
Return type:: list[str]
Returns:: The placeholder names in the order they appear in the pattern.

steplib.core.i18n.validate_i18n_consistency(info)[source]¶

Check that all patterns in a StepInfo share the same placeholders.

Parameters:: info (StepInfo) – The step metadata to validate.
Return type:: list[str]
Returns:: A list of human-readable error messages (empty if valid).

Validation¶

Static validation of step contracts.

Checks that every registered step satisfies the rules described in design-03-step-contract.md:

Patterns are parseable by parse.
Parameter names match pattern placeholders.
No duplicate patterns within the same backend.
i18n translations have the same placeholders as the base pattern.
Stacked patterns share the same placeholders and order.
Each step has a category.

steplib.core.validation.validate_steps(registry)[source]¶

Validate all steps in the registry.

Parameters:: registry (StepRegistry) – The registry to validate.
Return type:: list[str]
Returns:: A list of human-readable error messages (empty if all steps are valid).

Ecosystem¶

Ecosystem integration helpers for behave-kit, behave-tables and behave-data.

These functions lazily import the corresponding libraries and raise MissingDependencyError with the appropriate extra name if the library is not installed.

steplib.core.ecosystem.assert_soft(condition, message='')[source]¶

Perform a soft assertion using behave-kit.

Parameters:

condition (bool) – The condition to assert.
message (str) – Optional message to display on failure.

Raises:

MissingDependencyError – If behave-kit is not installed.

Return type:

None

steplib.core.ecosystem.check_behave_doctor_available()[source]¶

Check if behave-doctor is installed.

Return type:: bool
Returns:: True if behave-doctor is importable, False otherwise.

steplib.core.ecosystem.check_behave_model_available()[source]¶

Check if behave-model is installed.

Return type:: bool
Returns:: True if behave-model is importable, False otherwise.

steplib.core.ecosystem.load_test_data(source, **kwargs)[source]¶

Load test data from a file using behave-data.

Parameters:

source (str) – Path or URL to the data file (CSV, JSON, YAML, Excel).
**kwargs (Any) – Additional arguments passed to behave-data.

Return type:

Any

Returns:

The loaded data.

Raises:

MissingDependencyError – If behave-data is not installed.
StepContractError – If behave-data is installed but has no load function.

steplib.core.ecosystem.wrap_table(table)[source]¶

Wrap a behave table using behave-tables for easy conversion.

Parameters:: table (Any) – The context.table object from behave.
Return type:: Any
Returns:: A wrapped table object with methods like as_dicts().
Raises:: MissingDependencyError – If behave-tables is not installed.

Exceptions¶

Custom exceptions for steplib.

exception steplib.core.exceptions.DuplicateStepError(pattern, backend=None)[source]¶

Bases: SteplibError

Raised when two steps register the same pattern in the same backend.

exception steplib.core.exceptions.MissingDependencyError(extra, package=None)[source]¶

Bases: SteplibError

Raised when an optional dependency (extra) is not installed.

extra¶: The name of the missing extra (e.g. "api", "kit").

package¶: The import name of the missing package, if known.

exception steplib.core.exceptions.StepContractError[source]¶

Bases: SteplibError

Raised when a step function does not satisfy the step contract.

exception steplib.core.exceptions.SteplibError[source]¶

Bases: Exception

Base exception for all steplib errors.

Behave integration¶

Integration helpers for behave’s environment.py.

before_all and after_scenario can be imported directly as behave hooks. before_scenario must be written by the user (it calls context.steplib.reset()).

Usage:

# features/environment.py
from steplib.behave import after_scenario, before_all

def before_scenario(context, scenario):
    context.steplib.reset()

class steplib.behave.SteplibState(context, registry)[source]¶

Bases: object

Holds the steplib state attached to context.steplib.

Modules set their own namespaces as attributes on this object (e.g. state.api = ApiContext(...)).

Parameters:

context (Any) – The behave context object.
registry (StepRegistry) – The StepRegistry populated during autoload/load.

cleanup()[source]¶

Close resources after a scenario.

Called from after_scenario. Iterates over all module-level attributes (non-underscore) and calls cleanup() if available.

Return type:: None

property context: Any¶: The behave context.

property registry: StepRegistry¶: The step registry.

reset()[source]¶

Reset per-scenario state.

Called from before_scenario. Iterates over all module-level attributes (non-underscore) and calls reset() if available.

Return type:: None

steplib.behave.after_scenario(context, scenario)[source]¶

Clean up steplib resources after a scenario.

Parameters:

context (Any) – The behave context object.
scenario (Any) – The behave scenario object (unused but required by the hook).

Return type:

None

steplib.behave.autoload(context, categories=None, backends=None)[source]¶

Load all installed steplib plugins and attach state to context.

See steplib.core.discovery.autoload() for details.

Parameters:

context (Any) – The behave context object.
categories (list[str] | None) – Optional list of categories to keep (e.g. ["api"]).
backends (dict[str, str] | None) – Optional mapping of category to backend (e.g. {"api": "httpx"}).

Return type:

SteplibState

Returns:

A SteplibState holding the filtered registry.

steplib.behave.before_all(context)[source]¶

Run autoload and attach steplib state to context.

Parameters:: context (Any) – The behave context object.
Return type:: SteplibState
Returns:: The SteplibState attached to context.steplib.

steplib.behave.load(context, *modules)[source]¶

Load specific step modules by dotted path.

See steplib.core.discovery.load() for details.

Parameters:

context (Any) – The behave context object.
*modules (str) – Dotted module paths to import.

Return type:

SteplibState

Returns:

A SteplibState holding the registry.