or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

compilation.mdindex.mdlanguage-support.mdparsing.mdstream-processing.md
tile.json

tessl/pypi-gherkin-official

Python Gherkin parser that converts Gherkin feature files into structured data for behavior-driven development testing frameworks

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/gherkin-official@34.0.x

To install, run

npx @tessl/cli install tessl/pypi-gherkin-official@34.0.0

index.mddocs/

Gherkin Official

Python Gherkin parser that converts Gherkin feature files into structured data for behavior-driven development (BDD) testing frameworks. This is the official Gherkin parser implementation by the Cucumber team, supporting all Gherkin language features including features, scenarios, scenario outlines, examples tables, and backgrounds across 70+ natural languages.

Package Information

  • Package Name: gherkin-official
  • Package Type: pypi
  • Language: Python
  • Installation: pip install gherkin-official

Core Imports

from gherkin import Parser, Compiler

For stream processing:

from gherkin.stream.gherkin_events import GherkinEvents

Basic Usage

from gherkin import Parser, Compiler
from gherkin.stream.id_generator import IdGenerator

# Create parser and compiler instances
id_generator = IdGenerator()
parser = Parser()
compiler = Compiler(id_generator)

# Parse Gherkin feature file content
gherkin_text = """
Feature: Basic addition
  Scenario: Add two numbers
    Given I have entered 50 into the calculator
    And I have entered 70 into the calculator
    When I press add
    Then the result should be 120 on the screen
"""

# Parse to AST
gherkin_document = parser.parse(gherkin_text)
print(f"Feature: {gherkin_document['feature']['name']}")

# Compile to test pickles
gherkin_document_with_uri = {**gherkin_document, "uri": "example.feature"}
pickles = compiler.compile(gherkin_document_with_uri)

for pickle in pickles:
    print(f"Scenario: {pickle['name']}")
    for step in pickle['steps']:
        print(f"  {step['type']}: {step['text']}")

Architecture

The Python Gherkin parser follows a multi-stage processing architecture:

  • Parser: Core Parser class that tokenizes and builds Abstract Syntax Trees (AST) from Gherkin text
  • Compiler: Compiler class that transforms AST into test-executable "pickles" with scenario expansion
  • Token Processing: TokenScanner and matcher classes for lexical analysis and syntax recognition
  • Multi-format Support: Separate token matchers for classic .feature files and Gherkin-in-Markdown
  • Language Support: Built-in dialect system supporting 70+ natural languages via Dialect class
  • Stream Processing: High-level GherkinEvents API for processing multiple sources with comprehensive error handling

Capabilities

Core Parsing

Primary parsing functionality for converting Gherkin text into structured AST format with comprehensive error handling and language support.

class Parser:
    def __init__(self, ast_builder: AstBuilder | None = None) -> None: ...
    def parse(
        self,
        token_scanner_or_str: TokenScanner | str,
        token_matcher: TokenMatcher | None = None,
    ) -> GherkinDocument: ...
    stop_at_first_error: bool

Parsing

Pickle Compilation

Transforms parsed AST into executable test scenarios ("pickles") with scenario outline expansion and tag inheritance.

class Compiler:
    def __init__(self, id_generator: IdGenerator | None = None) -> None: ...
    def compile(self, gherkin_document: GherkinDocumentWithURI) -> list[Pickle]: ...
    id_generator: IdGenerator

Compilation

Stream Processing

High-level API for processing multiple Gherkin sources with configurable output formats and comprehensive error handling.

class GherkinEvents:
    @dataclass
    class Options:
        print_source: bool
        print_ast: bool
        print_pickles: bool
    
    def __init__(self, options: Options) -> None: ...
    def enum(
        self, source_event: Event
    ) -> Generator[Event | Error | GherkinDocumentEnvelope | PickleEnvelope]: ...

Stream Processing

Language and Dialect Support

Multi-language keyword support for international BDD development with dynamic dialect loading.

class Dialect:
    @classmethod
    def for_name(cls, name: str) -> Self | None: ...
    def __init__(self, spec: DialectSpec) -> None: ...
    @property
    def feature_keywords(self) -> list[str]: ...
    @property
    def scenario_keywords(self) -> list[str]: ...
    @property
    def given_keywords(self) -> list[str]: ...
    @property
    def when_keywords(self) -> list[str]: ...
    @property
    def then_keywords(self) -> list[str]: ...

Language Support

Types

Core Data Structures

class GherkinDocument(TypedDict):
    feature: Feature | None
    comments: list[Comment]

class Feature(TypedDict):
    location: Location
    tags: list[Tag] 
    language: str
    keyword: str
    name: str
    description: str
    children: list[Envelope]

class Scenario(TypedDict):
    location: Location
    tags: list[Tag]
    keyword: str
    name: str
    description: str
    steps: list[Step]
    examples: list[Examples]
    id: str

class Step(TypedDict):
    location: Location
    keyword: str
    keywordType: str
    text: str
    docString: DocString | None
    dataTable: DataTable | None
    id: str

Error Handling

class ParserException(Exception):
    def __init__(self, message: str, location: Location) -> None: ...
    location: Location

class CompositeParserException(Exception):
    def __init__(self, errors: list[ParserException]) -> None: ...
    errors: list[ParserException]

class NoSuchLanguageException(ParserException):
    def __init__(self, language: str, location: Location) -> None: ...