{"id":3501,"library":"gherkin-official","title":"Gherkin Official Parser for Python","description":"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.","status":"active","version":"39.0.0","language":"en","source_language":"en","source_url":"https://github.com/cucumber/gherkin","tags":["gherkin","cucumber","bdd","parser"],"install":[{"cmd":"pip install gherkin-official","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Used for type hinting support.","package":"typing-extensions","optional":false}],"imports":[{"note":"The Parser class is directly available from the `gherkin` package, not a top-level `gherkin` object that needs instantiation or deeper module access.","wrong":"import gherkin; parser = gherkin.Parser()","symbol":"Parser","correct":"from gherkin import Parser"},{"symbol":"Compiler","correct":"from gherkin import Compiler"}],"quickstart":{"code":"from gherkin import Parser, Compiler\n\nfeature_text = \"\"\"\nFeature: Calculator\n  As a math enthusiast\n  I want to add numbers\n  So I can avoid mental arithmetic\n\n  Scenario: Add two numbers\n    Given I have entered 50 into the calculator\n    And I have entered 70 into the calculator\n    When I press add\n    Then the result should be 120\n\"\"\"\n\nparser = Parser()\ngherkin_document = parser.parse(feature_text)\ngherkin_document[\"uri\"] = \"test.feature\" # Add a URI for the document\n\ncompiler = Compiler()\npickles = compiler.compile(gherkin_document)\n\nprint(f\"Parsed Gherkin Document: {gherkin_document}\")\nprint(f\"Compiled Pickles: {pickles}\")\n\n# Example of accessing data\nif pickles:\n    first_pickle = pickles[0]\n    print(f\"\\nFirst Pickle Name: {first_pickle['name']}\")\n    print(f\"First Pickle Steps: {[step['text'] for step in first_pickle['steps']]}\")","lang":"python","description":"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."},"warnings":[{"fix":"Ensure your project runs on Python 3.9 or a newer supported version.","message":"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.","severity":"breaking","affected_versions":"39.0.0+"},{"fix":"Review and update `.feature` files to strictly adhere to the current Gherkin specification. Consult the Gherkin reference for up-to-date syntax.","message":"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.","severity":"breaking","affected_versions":"Primarily 8.0.0+ (reflected in tools like pytest-bdd's adoption of this parser) and 39.0.0+ for `Rule` support."},{"fix":"Direct all development-related inquiries, bug reports, and pull requests to the main `cucumber/gherkin` repository (https://github.com/cucumber/gherkin).","message":"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.","severity":"gotcha","affected_versions":"All versions (since the archiving of `gherkin-python` in Nov 2022)."},{"fix":"Directly use the `gherkin-official` library's Python API (`from gherkin import Parser, Compiler`) for parsing and compiling Gherkin features within your applications.","message":"The `gherkin` command-line script, which was primarily used for internal acceptance tests, has been removed.","severity":"deprecated","affected_versions":"39.0.0+"},{"fix":"Always use `from gherkin import Parser, Compiler` to access the core functionality.","message":"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`.","severity":"gotcha","affected_versions":"Older versions prior to widespread adoption and clarity on import paths (e.g., before 27.0.0 where package name became `gherkin-official`)."}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}