Gherkin Official Parser for Python

39.0.0 · active · verified Sat Apr 11

Gherkin parser (official, by Cucumber team). It is a parser and compiler for the Gherkin language, which is a business-readable, domain-specific language used in Behavior-Driven Development (BDD) to describe software's behavior. It is developed and maintained by the Cucumber team and is designed to produce easily consumable Abstract Syntax Tree (AST) and Pickle objects. As of version 39.0.0, it officially supports Python versions 3.9 through 3.13. Releases are frequent, aligning with the broader Cucumber ecosystem development.

Warnings

breaking Python 2 and Python 3.8 are no longer supported as of version 39.0.0. The library now requires Python 3.9 or newer.
Fix: Ensure your project runs on Python 3.9 or a newer supported version.
breaking The Gherkin grammar and specification compatibility has evolved. Significant changes include: the `Feature:` keyword is now mandatory, multiline steps must consistently use triple-quotes, tags no longer permit spaces (e.g., `@tag one` is invalid), and the `Rule` keyword is now officially supported.
Fix: Review and update `.feature` files to strictly adhere to the current Gherkin specification. Consult the Gherkin reference for up-to-date syntax.
gotcha The dedicated `cucumber/gherkin-python` GitHub repository is now read-only and archived. For active development, issues, and contributions, refer to the main polyglot `cucumber/gherkin` monorepo.
Fix: Direct all development-related inquiries, bug reports, and pull requests to the main `cucumber/gherkin` repository (https://github.com/cucumber/gherkin).
deprecated The `gherkin` command-line script, which was primarily used for internal acceptance tests, has been removed.
Fix: Directly use the `gherkin-official` library's Python API (`from gherkin import Parser, Compiler`) for parsing and compiling Gherkin features within your applications.
gotcha In older setups, users sometimes incorrectly tried to import from `gherkin3` or found that a direct `import gherkin` didn't expose parser methods. The correct and consistent import is `from gherkin import Parser, Compiler`.
Fix: Always use `from gherkin import Parser, Compiler` to access the core functionality.

Install

pip install gherkin-official Install latest version

Imports

Parser
```
from gherkin import Parser
```
The Parser class is directly available from the `gherkin` package, not a top-level `gherkin` object that needs instantiation or deeper module access.
Compiler
```
from gherkin import Compiler
```

Quickstart

This quickstart demonstrates how to parse Gherkin feature text into a Gherkin Document Abstract Syntax Tree (AST) and then compile it into 'Pickle' objects, which are simplified representations suitable for execution. It also shows basic access to the parsed data.

from gherkin import Parser, Compiler

feature_text = """
Feature: Calculator
  As a math enthusiast
  I want to add numbers
  So I can avoid mental arithmetic

  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
"""

parser = Parser()
gherkin_document = parser.parse(feature_text)
gherkin_document["uri"] = "test.feature" # Add a URI for the document

compiler = Compiler()
pickles = compiler.compile(gherkin_document)

print(f"Parsed Gherkin Document: {gherkin_document}")
print(f"Compiled Pickles: {pickles}")

# Example of accessing data
if pickles:
    first_pickle = pickles[0]
    print(f"\nFirst Pickle Name: {first_pickle['name']}")
    print(f"First Pickle Steps: {[step['text'] for step in first_pickle['steps']]}")

view raw JSON →