Document Python usage

Author: kieran-ryan

README.md

@@ -224,8 +224,7 @@ Then this expression would match the following example:
     I have 1 \{what} cucumber in my belly \(amazing!)
     I have 42 \{what} cucumbers in my belly \(amazing!)
 
-There is currently no way to escape a `/` character - it will always be interpreted
-as alternative text.
+The `/` character will always be interpreted as an alternative, unless escaped, such as with `\/`.
 
 ## Architecture
 

python/README.md

@@ -5,27 +5,96 @@
 ![LICENSE](https://img.shields.io/badge/license-MIT-blue)
 [![test-python](https://github.com/cucumber/cucumber-expressions/actions/workflows/test-python.yml/badge.svg)](https://github.com/cucumber/cucumber-expressions/actions/workflows/test-python.yml)
 
-For detailed documentation on Cucumber Expressions, visit the [main docs](https://github.com/cucumber/cucumber-expressions#readme).
+For detailed documentation on __Cucumber Expressions__, visit the [main docs](https://github.com/cucumber/cucumber-expressions#readme).
 
-Cucumber Expressions are presently unsupported natively by common Python frameworks such as [behave](https://behave.readthedocs.io) and [pytest-bdd](https://pytest-bdd.readthedocs.io). However support can be integrated.
+## Installation
 
-> For pytest-bdd, see the [pytest-bdd-ng](https://pytest-bdd-ng.readthedocs.io) fork and its documentation on [how to use Cucumber Expressions](https://pytest-bdd-ng.readthedocs.io/en/default/#step-parameters). It should be noted that this fork is out of date with the latest releases.
+__Cucumber Expressions__ is available via [PyPI](https://pypi.org/project/cucumber-expressions/):
 
-## Using Cucumber Expressions with Behave
+```console
+pip install cucumber-expressions
+```
 
-Native support for Cucumber Expressions in _behave_ is presently unavailable. To enable support, a compatible step matcher must be defined and patched into its matchers. The following steps walk through this process.
+## Usage
 
-```console
-pip install cuke4behave
-pip install "cucumber-expressions>17.0.1"
+Cucumber Expressions can be used in numerous contexts as a human-friendly substitution for Regular Expressions.
+
+```python
+>>> from cucumber_expressions.expression import CucumberExpression
+>>> from cucumber_expressions.parameter_type_registry import ParameterTypeRegistry
+>>> registry = ParameterTypeRegistry()
+>>> expression = CucumberExpression("I have {int} cucumbers in my belly", registry)
+>>> expression.regexp
+'^I have ((?:-?\\d+)|(?:\\d+)) cucumbers in my belly$'
+>>> match = expression.match("I have 42 cucumbers in my belly")
+>>> match
+[<cucumber_expressions.argument.Argument object at 0x10dcf7650>]
+>>> argument = match[0]
+>>> argument.value
+42
 ```
 
-Define a Cucumber Expressions step matcher inside `environment.py` in your `features` directory.
+### Using Cucumber Expressions with Behave
+
+Native support for Cucumber Expressions in [behave](https://behave.readthedocs.io) is presently unavailable. To enable support, a compatible step matcher must be defined and patched into Behave's matchers. The following steps walk through this process.
+
+Define a Cucumber Expressions step matcher for Behave inside `cucumber_matcher.py` in your `features` directory.
 
 ```python
-from behave.matchers import matcher_mapping, use_step_matcher
+from behave.matchers import Matcher
+from behave.model_core import Argument
+from cucumber_expressions.expression import CucumberExpression
+
+
+class CucumberExpressionMatcher(Matcher):
+
+    def __init__(
+        self,
+        func,
+        pattern,
+        step_type= None,
+        parameter_type_registry = None,
+    ):
+        super().__init__(func, pattern, step_type)
+        self.func = func
+        self.pattern = pattern
+        self.parameter_type_registry = parameter_type_registry
+        self.__cucumber_expression_ = CucumberExpression(
+            pattern, self.parameter_type_registry
+        )
+
+    def check_match(self, step):
+        result = self.__cucumber_expression_.match(step)
+        if result is None:
+            return None
+        return [
+            Argument(x.group.start, x.group.end, str(x.value), x.value)
+            for x in result
+        ]
+
+    @property
+    def regex_pattern(self):
+        self.__cucumber_expression_.regexp
+
+
+def build_step_matcher(parameter_type_registry):
+    def step_matcher(func, pattern):
+        return CucumberExpressionMatcher(
+            func,
+            pattern,
+            parameter_type_registry=parameter_type_registry
+        )
+    return step_matcher
+
+```
+
+Import and patch the matcher into Behave inside `environment.py` in your `features` directory.
+
+```python
+from behave.matchers import use_step_matcher, matcher_mapping
 from cucumber_expressions.parameter_type_registry import ParameterTypeRegistry
-from cuke4behave.step_matcher import build_step_matcher
+
+from cucumber_matcher import build_step_matcher
 
 # Initialise a Cucumber Expressions parameter registry
 parameter_registry = ParameterTypeRegistry()
@@ -48,60 +117,71 @@ Feature: Color selection
   Rule: User can select a profile color
 
     Scenario: User selects a valid color
-      Given I am on the profile customization page
-      When I select the color "red"
-      Then the profile color should change to "red"
+      Given I am on the profile settings page
+      When I select the theme colour "red"
+      Then the profile colour should be "red"
 ```
 
 Create step definitions inside `color.py` in your `features/steps` directory:
 
 ```python
-from behave import given, when, then
-from behave.matchers import matcher_mapping
+from behave import given, then, when
 from cucumber_expressions.parameter_type import ParameterType
 
+from environment import parameter_registry
+
 # Define the parameter type
 color = ParameterType(
     name="color",
     regexp="red|blue|yellow",
     type=str,
     transformer=lambda s: s,
+    use_for_snippets=True,
+    prefer_for_regexp_match=False,
 )
 
 # Pass the parameter type to the registry instance
-matcher = matcher_mapping["cucumber_expressions"](None, "")
-parameter_registry = matcher.parameter_type_registry
 parameter_registry.define_parameter_type(color)
 
-
-@given("I am on the profile customization page")
-def step_given(context, page):
+@given("I am on the profile customisation/settings page")
+def step_given(context):
     assert True
 
-
 # Reference the parameter type in the step definition pattern
-@when('I select the color "{color}"')
-def step_when(context, color):
+@when('I select the theme colo(u)r "{color}"')
+def step_when(context, selected_color):
     assert color
-    context.selected_color = color
-
+    context.selected_color = selected_color
 
-@then('the profile color should change to "{color}"')
-def step_then(context, color):
+@then('the profile colo(u)r should be "{color}"')
+def step_then(context, displayed_color):
     assert color
-    assert context.selected_color == color
+    assert context.selected_color == displayed_color
+
+```
+
+The necessary files are now in place to execute our gherkin scenario.
+
+```console
+repository/
+  └── features/
+      ├── steps/
+      │   └── color.py
+      ├── cucumber_matcher.py
+      ├── environment.py
+      └── color.feature
 ```
 
 Finally, execute Behave. The scenario will run with the step definitions using the Cucumber Expressions parameter type.
 
 ```console
-➜ behave
-Feature: Color selection # features/color.feature:1
+$ behave features
+Feature: Color selection # features/Gherkin.feature:1
   Rule: User can select a profile color
-  Scenario: User selects a valid color            # features/color.feature:5
-    Given I am on the profile customization page  # features/steps/color.py:21 0.000s
-    When I select the color "red"                 # features/steps/color.py:27 0.000s
-    Then the profile color should change to "red" # features/steps/color.py:33 0.000s
+  Scenario: User selects a valid color      # features/Gherkin.feature:5
+    Given I am on the profile settings page # features/steps/color.py:20 0.000s
+    When I select the theme colour "red"    # features/steps/color.py:26 0.000s
+    Then the profile colour should be "red" # features/steps/color.py:32 0.000s
 
 1 feature passed, 0 failed, 0 skipped
 1 scenario passed, 0 failed, 0 skipped
@@ -111,4 +191,12 @@ Took 0m0.001s
 
 For detailed usage of _behave_, see the [official documentation](https://behave.readthedocs.io).
 
-> Note: Alternatives and optionals are currently unsupported with the above example.
+### Using Cucumber Expressions with pytest-bdd
+
+Native support for Cucumber Expressions in [pytest-bdd](https://pytest-bdd.readthedocs.io) is presently unavailable. However the [pytest-bdd-ng](https://pytest-bdd-ng.readthedocs.io) fork provides integrated support. Follow its documentation on [how to use Cucumber Expressions](https://pytest-bdd-ng.readthedocs.io/en/default/#step-parameters).
+
+> It should be noted that _pytest-bdd-ng_ is out of date with the latest releases of pytest-bdd.
+
+## License
+
+__Cucumber Expressions__ is licensed under the MIT License.