behave-steplib 1.0.1.dev0__py3-none-any.whl

behave_steplib-1.0.1.dev0.dist-info/METADATA

@@ -0,0 +1,303 @@
+Metadata-Version: 2.4
+Name: behave-steplib
+Version: 1.0.1.dev0
+Summary: Librería de steps reusable para behave con soporte multitecnología e i18n.
+Project-URL: Homepage, https://github.com/MathiasPaulenko/behave-steplib
+Project-URL: Documentation, https://mathiaspaulenko.github.io/behave-steplib
+Project-URL: Repository, https://github.com/MathiasPaulenko/behave-steplib
+Project-URL: Issues, https://github.com/MathiasPaulenko/behave-steplib/issues
+Project-URL: Changelog, https://github.com/MathiasPaulenko/behave-steplib/blob/main/CHANGELOG.md
+Author: Mathias Paulenko
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,bdd,behave,db,i18n,kafka,steps,web
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Testing
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: behave>=1.3.0
+Requires-Dist: parse>=1.19
+Requires-Dist: typer>=0.12
+Provides-Extra: all
+Requires-Dist: behave-data>=1.0.2; extra == 'all'
+Requires-Dist: behave-kit>=1.3.1; extra == 'all'
+Requires-Dist: behave-tables>=1.3.1; extra == 'all'
+Requires-Dist: httpx>=0.27; extra == 'all'
+Requires-Dist: kafka-python-ng>=2.0; extra == 'all'
+Requires-Dist: selenium>=4.0; extra == 'all'
+Requires-Dist: sqlalchemy>=2.0; extra == 'all'
+Provides-Extra: api
+Requires-Dist: httpx>=0.27; extra == 'api'
+Provides-Extra: data
+Requires-Dist: behave-data>=1.0.2; extra == 'data'
+Provides-Extra: db
+Requires-Dist: sqlalchemy>=2.0; extra == 'db'
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pre-commit>=3.7; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: responses>=0.25; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: furo>=2024.0; extra == 'docs'
+Requires-Dist: myst-parser>=3.0; extra == 'docs'
+Requires-Dist: sphinx-autodoc-typehints>=2.0; extra == 'docs'
+Requires-Dist: sphinx>=7.0; extra == 'docs'
+Provides-Extra: kafka
+Requires-Dist: kafka-python-ng>=2.0; extra == 'kafka'
+Provides-Extra: kit
+Requires-Dist: behave-kit>=1.3.1; extra == 'kit'
+Provides-Extra: tables
+Requires-Dist: behave-tables>=1.3.1; extra == 'tables'
+Provides-Extra: web
+Requires-Dist: selenium>=4.0; extra == 'web'
+Description-Content-Type: text/markdown
+
+# behave-steplib
+
+Reusable step libraries for [Behave](https://github.com/behave/behave) BDD — share, discover and install step definitions across projects. Zero mandatory dependencies; each technology is an optional extra.
+
+[![CI](https://github.com/MathiasPaulenko/behave-steplib/actions/workflows/ci.yml/badge.svg)](https://github.com/MathiasPaulenko/behave-steplib/actions/workflows/ci.yml)
+[![Release](https://github.com/MathiasPaulenko/behave-steplib/actions/workflows/release.yml/badge.svg)](https://github.com/MathiasPaulenko/behave-steplib/actions/workflows/release.yml)
+[![PyPI](https://img.shields.io/pypi/v/behave-steplib.svg)](https://pypi.org/project/behave-steplib/)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Why behave-steplib?
+
+Writing BDD step definitions for HTTP APIs, web browsers, databases and Kafka is repetitive. Every project re-implements the same "send a request", "check the status code", "query the database" steps. behave-steplib provides a curated, typed, multilingual library of reusable steps that you install once and share across projects.
+
+- **Modular** — `api`, `web`, `db`, `kafka` modules activated via extras and lazy imports. Install only what you need.
+- **Auto-registered** — `autoload(context)` discovers every installed step via Python entry points and registers it with behave in one line.
+- **Multilingual** — steps defined in English with `es` and `pt` translations; all patterns are registered with behave so matching works regardless of the language used in feature files.
+- **Typed** — full type hints, `mypy --strict` clean, `py.typed` marker included.
+- **CLI** — `steplib list / show / validate / init` powered by Typer for inspecting and validating your step library from the terminal.
+- **Pluggable** — third-party packages can register steps via the `steplib.plugins` entry point group; `autoload` discovers them automatically.
+- **Ecosystem** — integrates with `behave-kit` (soft assertions), `behave-tables` (table conversion) and `behave-data` (test data loading) when installed.
+- **Backends** — each module supports multiple backends (e.g. stdlib/httpx/requests for API, selenium for web) selectable at autoload time.
+
+## Installation
+
+```bash
+pip install behave-steplib            # core only (behave, parse, typer)
+pip install behave-steplib[api]       # + httpx HTTP client
+pip install "behave-steplib[api,web,db,kafka]"  # + all technology extras
+pip install "behave-steplib[all]"     # + every technology extra
+pip install behave-steplib[dev]       # + pytest, ruff, mypy, build, twine
+```
+
+| Extra | Packages | Description |
+|-------|----------|-------------|
+| `[api]` | `httpx` | HTTP API testing with httpx |
+| `[web]` | `selenium` | Browser testing with Selenium |
+| `[db]` | `sqlalchemy` | Database testing with SQLAlchemy |
+| `[kafka]` | `kafka-python-ng` | Kafka producer/consumer testing |
+| `[kit]` | `behave-kit` | Soft assertions, typed context, fixtures |
+| `[data]` | `behave-data` | Test data loading (CSV, JSON, YAML, Excel) |
+| `[tables]` | `behave-tables` | Table conversion helpers |
+| `[dev]` | pytest, ruff, mypy, build, twine | Development tools |
+| `[docs]` | sphinx, furo, myst-parser | Documentation tools |
+| `[all]` | api, web, db, kafka, kit, data, tables | Everything except dev/docs |
+
+## Quickstart
+
+### Level 1 — Automatic wiring
+
+Add three hooks to your `environment.py` and every installed step is wired automatically:
+
+```python
+# features/environment.py
+from steplib.behave import autoload
+
+def before_all(context):
+    context.steplib = autoload(context)
+
+def before_scenario(context, scenario):
+    context.steplib.reset()
+
+def after_scenario(context, scenario):
+    context.steplib.cleanup()
+```
+
+Or generate it with the CLI:
+
+```bash
+steplib init
+```
+
+### Level 2 — Explicit load
+
+Load only the modules you need by dotted path:
+
+```python
+from steplib.behave import load
+
+def before_all(context):
+    context.steplib = load(context, "steplib.modules.api.steps")
+```
+
+### Level 3 — Filtered autoload
+
+When multiple extras are installed, narrow which steps are active:
+
+```python
+from steplib.behave import autoload
+
+def before_all(context):
+    context.steplib = autoload(
+        context,
+        categories=["api"],
+        backends={"api": "httpx"},
+    )
+```
+
+### Example feature
+
+```gherkin
+Feature: API health check
+
+  Scenario: GET users returns 200
+    Given the API base url is "https://api.example.com"
+    When I send a GET request to "/users"
+    Then the response status is 200
+    And the response body is valid JSON
+    And the JSON path "$.users[0].name" equals "Ada"
+```
+
+### Multilingual features
+
+Steps are defined in English and translated to Spanish and Portuguese. All patterns are registered with behave — no language switch needed:
+
+```gherkin
+# es
+Cuando envío una petición GET a "/users"
+Entonces el estado de la respuesta es 200
+
+# pt
+Quando envio uma requisição GET para "/users"
+Então o status da resposta é 200
+```
+
+## Modules
+
+### API
+
+HTTP API testing with stdlib (urllib), httpx or requests backends.
+
+```gherkin
+Given the API base url is "https://api.example.com"
+When I send a GET request to "/users"
+Then the response status is 200
+And the JSON path "$.users[0].name" equals "Ada"
+And the response header "Content-Type" is "application/json"
+```
+
+### Web
+
+Browser testing with Selenium (Chrome, Firefox, headless).
+
+```gherkin
+Given the web base url is "https://example.com"
+When I navigate to "/login"
+Then the page title is "Login"
+And the element id "username" is present
+And the page contains "Sign In"
+```
+
+### DB
+
+Database testing with SQLAlchemy (SQLite, PostgreSQL, MySQL, ...).
+
+```gherkin
+Given the database connection string is "sqlite:///test.db"
+When I execute the SQL query "SELECT * FROM users"
+Then the query returns 3 rows
+And the column "name" in the first row equals "Ada"
+```
+
+### Kafka
+
+Kafka producer and consumer testing with kafka-python-ng.
+
+```gherkin
+Given the Kafka bootstrap servers are "localhost:9092"
+When I produce a message to topic "events" with key "id" and value "hello"
+And I consume messages from topic "events"
+Then the consumed messages count is 1
+And a consumed message contains "hello"
+```
+
+## CLI
+
+```bash
+steplib list                         # list all registered steps
+steplib list --category api          # filter by category
+steplib list --backend httpx         # filter by backend
+steplib list --json                  # output as JSON
+steplib show "I send a {method} request to {url}"
+steplib validate                     # validate step contracts
+steplib init                         # generate features/environment.py
+```
+
+## Writing custom steps
+
+Use the `@step` decorator to define your own steps with full metadata:
+
+```python
+from steplib import Param, step
+
+@step(
+    "the invoice total is {total:f}",
+    category="invoice",
+    description="Assert the invoice total matches.",
+    parameters=[Param("total", type=float, required=True)],
+    example='Then the invoice total is 19.99',
+    i18n={
+        "es": "el total de la factura es {total:f}",
+        "pt": "o total da fatura é {total:f}",
+    },
+    tags=["invoice"],
+    version="1.0.0",
+)
+def step_invoice_total(context, total):
+    assert context.invoice.total == total
+```
+
+Register steps in a `register(registry)` function and declare an entry point:
+
+```toml
+# pyproject.toml
+[project.entry-points."steplib.plugins"]
+mycompany = "mycompany.steps:register"
+```
+
+Once installed, `autoload(context)` discovers your package automatically.
+
+## Development
+
+```bash
+make dev        # install with api, dev and docs extras
+make lint       # ruff + mypy --strict
+make test-cov   # pytest with >=80% coverage gate
+make docs-build # build Sphinx documentation
+make build      # build sdist + wheel
+```
+
+## Documentation
+
+Full documentation is available at <https://mathiaspaulenko.github.io/behave-steplib>.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

behave_steplib-1.0.1.dev0.dist-info/RECORD

@@ -0,0 +1,44 @@
+steplib/__init__.py,sha256=uHZuzdMz369B9Us648sLdwqo7qCR4S7fz9YXsafTfZ8,398
+steplib/_version.py,sha256=Y_mQou6Ma9bKGw0wGkSUgyT333rlwHalgPFv_DCW8mY,533
+steplib/behave.py,sha256=hyheeo7XjHbjWEXdud3UCAaQcV5HBK4kEC-9lNVELt0,1682
+steplib/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+steplib/cli/__init__.py,sha256=x-E6fqvwCyB59vrcFkgK1jbdwmE11-a7Hc2zvGwK_eM,47
+steplib/cli/formatters.py,sha256=PMFP0NmTf1NsryEhcE7Lg5iU2C81R7rxt7l-jHltzCQ,4903
+steplib/cli/main.py,sha256=2D1cTApiJ8Vo2YHU-hdIu3Mjp6AQ_86maCB13NR9rZ4,3920
+steplib/core/__init__.py,sha256=Ipdf6bddOFExw6FzX0ndHU5Q2vpRAMGLNtDDwQLUF5k,716
+steplib/core/decorators.py,sha256=3mWIWgO9HSsIY4_eHi4AFPVRUnWoBw0SSWdWRmYx5wc,3152
+steplib/core/discovery.py,sha256=4mAlk-_RptfOJwX4BkWlICd1x8gelb8kRKE26SSYsDc,3675
+steplib/core/ecosystem.py,sha256=P3Fo3sqFdrlmoxz-fuXuspH-45CHoBGt4_izb5pza0Q,2838
+steplib/core/exceptions.py,sha256=3RA4cPnaa4ogYFaDCUamBv7metqwP-C7g592JUpC6Cc,1469
+steplib/core/i18n.py,sha256=Qy8t8IYf0jrLel4TU5-uSjr6pNd4F6tQBxJoUC_dDTY,2356
+steplib/core/metadata.py,sha256=LAzpV1sDlglymScIDktz3ScaMNB5sAelBjJfO-edA9E,1443
+steplib/core/params.py,sha256=JGp9Ucrmc2smHCBsS0UHn_o5HYqX1Smn72Lkz_ok5tM,3554
+steplib/core/registry.py,sha256=DycbyUj8_4UzJmWQTtvodIMUlawNbv4Jcbbk4YwiBrQ,5789
+steplib/core/state.py,sha256=TVpq00E6uNyMbU69mV_F-eXzPnhNVY3DbtxNsbvCb-g,2014
+steplib/core/validation.py,sha256=UwRCdMp50J3y2YYu0Gfr5SBGvGnxlmZySMpYxeMvRRE,3338
+steplib/modules/__init__.py,sha256=Sfv7_PZXOAJnJFrODZ5XmbaAY3gx_7J6y5ytZNqxWjg,59
+steplib/modules/api/__init__.py,sha256=qR4iUPbYCUyA9hs5R8yt2HvCvlOlHBqIF3EyAxwCEoM,146
+steplib/modules/api/actions.py,sha256=4cdnG1_weBBQyAZV5o9UQp5eczQvRbTDtnJdjf1b5tI,5130
+steplib/modules/api/client.py,sha256=81C3oTW3svQMHJnkL18vHA-b5Kh1JJxzHwBrp5kcauI,5226
+steplib/modules/api/context.py,sha256=oebor5xzT4K03OLqEQCW_kj-IE89fQ9M2pp5ep_u0v0,1384
+steplib/modules/api/steps.py,sha256=ldfHLBmG2VmB17TfQrOQMRG6fdD5m9nV1G8IeQPBykU,8353
+steplib/modules/api/transforms.py,sha256=7DDp2S5iJ43UJa2S_57QM0TPhUQXLLVlvQcu6CPVR7g,4840
+steplib/modules/db/__init__.py,sha256=OaUBBRuzdETaB0qLY_tP1p_tWoUXidfqtSYJjci3nho,164
+steplib/modules/db/actions.py,sha256=W3Ax4O6LFTEf1AjX5LIp22_C8M3OQq7KJgYUrNyl-sA,2093
+steplib/modules/db/client.py,sha256=hYhfuWX4Aci9PXmgLWNhLCEZ_dFrITjBV_lXvyrWbAc,1841
+steplib/modules/db/context.py,sha256=0t92VVPCfcczdZlWv07YGimXlxwRWMqeRtpnq1w72Ug,1007
+steplib/modules/db/steps.py,sha256=Lg9w5A4Nd9aRlKH22XmI_CUe0KiK3_msjFdCATKWdnc,3843
+steplib/modules/kafka/__init__.py,sha256=PLsmP7fIXSGPKfEknjJZwjD-PrXcwxRYY2Lqj5EhLSQ,169
+steplib/modules/kafka/actions.py,sha256=LrFgpZrrCVnQ4l8Fjali4j4SpntVWwVNDTcT3H-A2FI,3427
+steplib/modules/kafka/context.py,sha256=R7PgMFFRF_J-Jq_BqXRmT_2xXkn3g9hof6P_Tvr_t0I,1031
+steplib/modules/kafka/steps.py,sha256=hbvUkFiS_QliIVJ65BBMFvBrehJRr9ijLT-7nssYcvA,4223
+steplib/modules/web/__init__.py,sha256=mGDM_4D2Xa04gBwiLkCPrtBzdCcgFf9y9w6qgMuDS4Y,163
+steplib/modules/web/actions.py,sha256=a7bv96_2AOOau_hvCKUek2ByO72yw9BYldCdhmCVedI,2505
+steplib/modules/web/client.py,sha256=Pu8ADRhvob5izdvkitIW-MFZCyMHNbAOGUamjf9o0qA,3276
+steplib/modules/web/context.py,sha256=ySz-wz1jHyOzycybfodCfibDh7Je0MEzfyD9UZ-bGDc,843
+steplib/modules/web/steps.py,sha256=h5VYIl31yKMmhPhWD1W0nYFP1r5fdzDC7cup4eyqjAI,3872
+behave_steplib-1.0.1.dev0.dist-info/METADATA,sha256=TK3WfqUtUkJO1mpSJ-roOiXOwbGFE5izdcWlHrpLrA0,10890
+behave_steplib-1.0.1.dev0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+behave_steplib-1.0.1.dev0.dist-info/entry_points.txt,sha256=tYJ2rN6gq8_reyWHDPBg8MklVdJnPfGNRZdZAH9QROk,235
+behave_steplib-1.0.1.dev0.dist-info/licenses/LICENSE,sha256=LLr8AP65kT83seFEcknE3-76LL7oikrP87U33tZKYro,1073
+behave_steplib-1.0.1.dev0.dist-info/RECORD,,

behave_steplib-1.0.1.dev0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

behave_steplib-1.0.1.dev0.dist-info/entry_points.txt

@@ -0,0 +1,8 @@
+[console_scripts]
+steplib = steplib.cli.main:main
+
+[steplib.plugins]
+api = steplib.modules.api.steps:register
+db = steplib.modules.db.steps:register
+kafka = steplib.modules.kafka.steps:register
+web = steplib.modules.web.steps:register

behave_steplib-1.0.1.dev0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Mathias Paulenko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

steplib/__init__.py

@@ -0,0 +1,18 @@
+"""behave-steplib — reusable step libraries for Behave BDD."""
+
+from __future__ import annotations
+
+try:
+    from steplib._version import __version__ as __version__
+except ImportError:  # pragma: no cover
+    __version__ = "0.0.0+unknown"
+
+from steplib.core import Param, StepInfo, StepRegistry, step
+
+__all__ = [
+    "Param",
+    "StepInfo",
+    "StepRegistry",
+    "__version__",
+    "step",
+]

steplib/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '1.0.1.dev0'
+__version_tuple__ = version_tuple = (1, 0, 1, 'dev0')
+
+__commit_id__ = commit_id = None

steplib/behave.py

@@ -0,0 +1,58 @@
+"""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()
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from steplib.core.discovery import autoload as _autoload
+from steplib.core.discovery import load as _load
+from steplib.core.state import SteplibState
+
+__all__ = ["SteplibState", "after_scenario", "autoload", "before_all", "load"]
+
+
+def autoload(
+    context: Any,
+    categories: list[str] | None = None,
+    backends: dict[str, str] | None = None,
+) -> SteplibState:
+    """Load all installed steplib plugins and attach state to *context*.
+
+    See :func:`steplib.core.discovery.autoload` for details.
+    """
+    return _autoload(context, categories=categories, backends=backends)
+
+
+def load(context: Any, *modules: str) -> SteplibState:
+    """Load specific step modules by dotted path.
+
+    See :func:`steplib.core.discovery.load` for details.
+    """
+    return _load(context, *modules)
+
+
+def before_all(context: Any) -> SteplibState:
+    """Run autoload and attach steplib state to *context*."""
+    state = autoload(context)
+    context.steplib = state
+    return state
+
+
+def after_scenario(context: Any, scenario: Any) -> None:
+    """Clean up steplib resources after a scenario."""
+    state = getattr(context, "steplib", None)
+    if state is not None and hasattr(state, "cleanup"):
+        state.cleanup()

steplib/cli/__init__.py

@@ -0,0 +1 @@
+"""CLI package: steplib terminal interface."""

steplib/cli/formatters.py

@@ -0,0 +1,166 @@
+"""Output formatters for the steplib CLI."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from steplib.core.metadata import StepInfo
+
+
+def format_step_table(steps: list[StepInfo]) -> str:
+    """Format a list of steps as a simple aligned table.
+
+    Args:
+        steps: The step metadata entries to render.
+
+    Returns:
+        A multi-line string with columns: PATTERN, CATEGORY, BACKEND, DESCRIPTION.
+
+    """
+    if not steps:
+        return "No steps found."
+
+    headers = ("PATTERN", "CATEGORY", "BACKEND", "DESCRIPTION")
+    rows: list[tuple[str, str, str, str]] = []
+    for info in steps:
+        rows.append((
+            info.pattern,
+            info.category,
+            info.backend or "-",
+            (info.description or "").split("\n")[0][:60],
+        ))
+
+    col_widths = [
+        max(len(str(row[i])) for row in [headers, *rows])
+        for i in range(len(headers))
+    ]
+
+    lines: list[str] = []
+    header_line = "  ".join(
+        headers[i].ljust(col_widths[i]) for i in range(len(headers))
+    )
+    lines.append(header_line)
+    lines.append("  ".join("-" * col_widths[i] for i in range(len(headers))))
+    for row in rows:
+        lines.append("  ".join(
+            str(row[i]).ljust(col_widths[i]) for i in range(len(headers))
+        ))
+    return "\n".join(lines)
+
+
+def format_step_detail(info: StepInfo) -> str:
+    """Format a single step's metadata for detailed display.
+
+    Args:
+        info: The step metadata to render.
+
+    Returns:
+        A multi-line string with all metadata fields.
+
+    """
+    lines: list[str] = [
+        f"Pattern:    {info.pattern}",
+        f"Category:   {info.category}",
+        f"Backend:    {info.backend or '-'}",
+        f"Module:     {info.module}",
+        f"Function:   {info.qualified_name}",
+    ]
+
+    if info.description:
+        lines.append(f"Description: {info.description}")
+    if info.example:
+        lines.append(f"Example:    {info.example}")
+    if info.tags:
+        lines.append(f"Tags:       {', '.join(info.tags)}")
+    if info.version:
+        lines.append(f"Version:    {info.version}")
+    if info.deprecated:
+        lines.append(f"Deprecated: {info.deprecated}")
+    if info.requires:
+        lines.append(f"Requires:   {', '.join(info.requires)}")
+
+    if info.parameters:
+        lines.append("Parameters:")
+        for param in info.parameters:
+            type_name = (
+                param.type.__name__ if isinstance(param.type, type)
+                else str(param.type)
+            )
+            default_hint = f", default {param.default!r}" if param.default is not None else ""
+            required_hint = " (required)" if param.required else ""
+            lines.append(
+                f"  - {param.name}: {type_name}{required_hint}{default_hint}"
+            )
+
+    if info.i18n:
+        lines.append("Translations:")
+        for lang, translated in info.i18n.items():
+            lines.append(f"  [{lang}] {translated}")
+
+    return "\n".join(lines)
+
+
+def format_step_json(steps: list[StepInfo]) -> str:
+    """Format a list of steps as a JSON array.
+
+    Args:
+        steps: The step metadata entries to serialize.
+
+    Returns:
+        A JSON string with pattern, category, backend, and description per step.
+
+    """
+    data: list[dict[str, Any]] = []
+    for info in steps:
+        data.append({
+            "pattern": info.pattern,
+            "category": info.category,
+            "backend": info.backend,
+            "description": info.description,
+            "module": info.module,
+            "tags": info.tags,
+            "version": info.version,
+            "deprecated": info.deprecated,
+            "example": info.example,
+            "i18n": info.i18n,
+        })
+    return json.dumps(data, indent=2, ensure_ascii=False)
+
+
+def format_step_detail_json(info: StepInfo) -> str:
+    """Format a single step's metadata as JSON.
+
+    Args:
+        info: The step metadata to serialize.
+
+    Returns:
+        A JSON string with all metadata fields.
+
+    """
+    data: dict[str, Any] = {
+        "pattern": info.pattern,
+        "category": info.category,
+        "backend": info.backend,
+        "description": info.description,
+        "module": info.module,
+        "function": info.qualified_name,
+        "example": info.example,
+        "tags": info.tags,
+        "version": info.version,
+        "deprecated": info.deprecated,
+        "requires": info.requires,
+        "i18n": info.i18n,
+        "parameters": [
+            {
+                "name": p.name,
+                "type": p.type.__name__ if isinstance(p.type, type) else str(p.type),
+                "required": p.required,
+                "default": p.default,
+                "description": p.description,
+                "choices": p.choices,
+            }
+            for p in info.parameters
+        ],
+    }
+    return json.dumps(data, indent=2, ensure_ascii=False)