0
# Gherkin Official
1
2
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.
3
4
## Package Information
5
6
- **Package Name**: gherkin-official
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: `pip install gherkin-official`
10
11
## Core Imports
12
13
```python
14
from gherkin import Parser, Compiler
15
```
16
17
For stream processing:
18
19
```python
20
from gherkin.stream.gherkin_events import GherkinEvents
21
```
22
23
## Basic Usage
24
25
```python
26
from gherkin import Parser, Compiler
27
from gherkin.stream.id_generator import IdGenerator
28
29
# Create parser and compiler instances
30
id_generator = IdGenerator()
31
parser = Parser()
32
compiler = Compiler(id_generator)
33
34
# Parse Gherkin feature file content
35
gherkin_text = """
36
Feature: Basic addition
37
Scenario: Add two numbers
38
Given I have entered 50 into the calculator
39
And I have entered 70 into the calculator
40
When I press add
41
Then the result should be 120 on the screen
42
"""
43
44
# Parse to AST
45
gherkin_document = parser.parse(gherkin_text)
46
print(f"Feature: {gherkin_document['feature']['name']}")
47
48
# Compile to test pickles
49
gherkin_document_with_uri = {**gherkin_document, "uri": "example.feature"}
50
pickles = compiler.compile(gherkin_document_with_uri)
51
52
for pickle in pickles:
53
print(f"Scenario: {pickle['name']}")
54
for step in pickle['steps']:
55
print(f" {step['type']}: {step['text']}")
56
```
57
58
## Architecture
59
60
The Python Gherkin parser follows a multi-stage processing architecture:
61
62
- **Parser**: Core `Parser` class that tokenizes and builds Abstract Syntax Trees (AST) from Gherkin text
63
- **Compiler**: `Compiler` class that transforms AST into test-executable "pickles" with scenario expansion
64
- **Token Processing**: `TokenScanner` and matcher classes for lexical analysis and syntax recognition
65
- **Multi-format Support**: Separate token matchers for classic `.feature` files and Gherkin-in-Markdown
66
- **Language Support**: Built-in dialect system supporting 70+ natural languages via `Dialect` class
67
- **Stream Processing**: High-level `GherkinEvents` API for processing multiple sources with comprehensive error handling
68
69
## Capabilities
70
71
### Core Parsing
72
73
Primary parsing functionality for converting Gherkin text into structured AST format with comprehensive error handling and language support.
74
75
```python { .api }
76
class Parser:
77
def __init__(self, ast_builder: AstBuilder | None = None) -> None: ...
78
def parse(
79
self,
80
token_scanner_or_str: TokenScanner | str,
81
token_matcher: TokenMatcher | None = None,
82
) -> GherkinDocument: ...
83
stop_at_first_error: bool
84
```
85
86
[Parsing](./parsing.md)
87
88
### Pickle Compilation
89
90
Transforms parsed AST into executable test scenarios ("pickles") with scenario outline expansion and tag inheritance.
91
92
```python { .api }
93
class Compiler:
94
def __init__(self, id_generator: IdGenerator | None = None) -> None: ...
95
def compile(self, gherkin_document: GherkinDocumentWithURI) -> list[Pickle]: ...
96
id_generator: IdGenerator
97
```
98
99
[Compilation](./compilation.md)
100
101
### Stream Processing
102
103
High-level API for processing multiple Gherkin sources with configurable output formats and comprehensive error handling.
104
105
```python { .api }
106
class GherkinEvents:
107
@dataclass
108
class Options:
109
print_source: bool
110
print_ast: bool
111
print_pickles: bool
112
113
def __init__(self, options: Options) -> None: ...
114
def enum(
115
self, source_event: Event
116
) -> Generator[Event | Error | GherkinDocumentEnvelope | PickleEnvelope]: ...
117
```
118
119
[Stream Processing](./stream-processing.md)
120
121
### Language and Dialect Support
122
123
Multi-language keyword support for international BDD development with dynamic dialect loading.
124
125
```python { .api }
126
class Dialect:
127
@classmethod
128
def for_name(cls, name: str) -> Self | None: ...
129
def __init__(self, spec: DialectSpec) -> None: ...
130
@property
131
def feature_keywords(self) -> list[str]: ...
132
@property
133
def scenario_keywords(self) -> list[str]: ...
134
@property
135
def given_keywords(self) -> list[str]: ...
136
@property
137
def when_keywords(self) -> list[str]: ...
138
@property
139
def then_keywords(self) -> list[str]: ...
140
```
141
142
[Language Support](./language-support.md)
143
144
## Types
145
146
### Core Data Structures
147
148
```python { .api }
149
class GherkinDocument(TypedDict):
150
feature: Feature | None
151
comments: list[Comment]
152
153
class Feature(TypedDict):
154
location: Location
155
tags: list[Tag]
156
language: str
157
keyword: str
158
name: str
159
description: str
160
children: list[Envelope]
161
162
class Scenario(TypedDict):
163
location: Location
164
tags: list[Tag]
165
keyword: str
166
name: str
167
description: str
168
steps: list[Step]
169
examples: list[Examples]
170
id: str
171
172
class Step(TypedDict):
173
location: Location
174
keyword: str
175
keywordType: str
176
text: str
177
docString: DocString | None
178
dataTable: DataTable | None
179
id: str
180
```
181
182
### Error Handling
183
184
```python { .api }
185
class ParserException(Exception):
186
def __init__(self, message: str, location: Location) -> None: ...
187
location: Location
188
189
class CompositeParserException(Exception):
190
def __init__(self, errors: list[ParserException]) -> None: ...
191
errors: list[ParserException]
192
193
class NoSuchLanguageException(ParserException):
194
def __init__(self, language: str, location: Location) -> None: ...