Add reboot.bdd: write Reboot tests in Gherkin with pytest-bdd

bazel/pip_package_rule/BUILD.bazel

@@ -21,6 +21,12 @@ exports_files(
 
 # A trampoline for the `pip_package` Bazel rule to invoke Python's `build` tool.
 # Should only be used via the `pip_package` Bazel rule.
+py_binary(
+    name = "strip_requirements",
+    srcs = ["strip_requirements.py"],
+    visibility = ["//visibility:public"],
+)
+
 py_binary(
     name = "build_trampoline",
     srcs = ["build_trampoline.py"],

bazel/pip_package_rule/build_trampoline.py

@@ -76,6 +76,7 @@ def find_package_name(line: str) -> str:
     parser.add_argument(
         "--requirements-txt",
         type=str,
+        action="append",
         help="the path to the requirements.txt file",
         required=True,
     )
@@ -114,17 +115,19 @@ def find_package_name(line: str) -> str:
         normalize_package_name(dep)
         for dep in args.verify_dependency_in_requirements
     ]
-    with open(args.requirements_txt) as requirements_txt:
-        for line in requirements_txt:
-            if line.startswith("#"):
-                continue
-            dependency = normalize_package_name(find_package_name(line))
-            try:
-                # This dependency is no longer missing!
-                missing_dependencies.remove(dependency)
-            except ValueError:
-                # Turns out we don't need this dependency. That's fine.
-                pass
+    for requirements_txt_path in args.requirements_txt:
+        with open(requirements_txt_path) as requirements_txt:
+            for line in requirements_txt:
+                if line.startswith("#"):
+                    continue
+                dependency = normalize_package_name(find_package_name(line))
+                try:
+                    # This dependency is no longer missing!
+                    missing_dependencies.remove(dependency)
+                except ValueError:
+                    # Turns out we don't need this dependency. That's
+                    # fine.
+                    pass
     if len(missing_dependencies) > 0:
         raise MissingDependenciesError(
             f"Expected dependencies {missing_dependencies} to be in the "

bazel/pip_package_rule/pip_package.bzl

@@ -560,16 +560,56 @@ def _pip_package_impl(ctx):
     staged_requirements_txt = ctx.actions.declare_file(
         "%s/requirements.txt" % STAGING_DIRECTORY_NAME,
     )
-    ctx.actions.run_shell(
-        mnemonic = "StageRequirements",
-        command = "cp %s %s" % (
+    extras_requirements_txts = {}
+    for extra_target, extra_name in ctx.attr.extras.items():
+        extra_files = extra_target[DefaultInfo].files.to_list()
+        if len(extra_files) != 1:
+            fail("Expected exactly one requirements file for extra '%s'" %
+                 extra_name)
+        extras_requirements_txts[extra_name] = extra_files[0]
+    if extras_requirements_txts:
+        strip_arguments = [
+            "--requirements-txt",
             input_requirements_txt.path,
+            "--output",
             staged_requirements_txt.path,
-        ),
-        inputs = [input_requirements_txt],
-        outputs = [staged_requirements_txt],
-    )
+        ]
+        for extra_file in extras_requirements_txts.values():
+            strip_arguments.append(
+                "--extra-requirements-txt=%s" % extra_file.path,
+            )
+        ctx.actions.run(
+            mnemonic = "StripExtrasRequirements",
+            executable = ctx.executable._strip_requirements_tool,
+            arguments = strip_arguments,
+            inputs = [input_requirements_txt] +
+                     extras_requirements_txts.values(),
+            outputs = [staged_requirements_txt],
+        )
+    else:
+        ctx.actions.run_shell(
+            mnemonic = "StageRequirements",
+            command = "cp %s %s" % (
+                input_requirements_txt.path,
+                staged_requirements_txt.path,
+            ),
+            inputs = [input_requirements_txt],
+            outputs = [staged_requirements_txt],
+        )
     metadata_files.append(staged_requirements_txt)
+    staged_extras_requirements_txts = []
+    for extra_name, extra_file in extras_requirements_txts.items():
+        staged_extra = ctx.actions.declare_file(
+            "%s/requirements-%s.txt" % (STAGING_DIRECTORY_NAME, extra_name),
+        )
+        ctx.actions.run_shell(
+            mnemonic = "StageExtraRequirements",
+            command = "cp %s %s" % (extra_file.path, staged_extra.path),
+            inputs = [extra_file],
+            outputs = [staged_extra],
+        )
+        metadata_files.append(staged_extra)
+        staged_extras_requirements_txts.append(staged_extra)
 
     ### pyproject.toml
     # The `pyproject.toml` file is the main configuration file that will control
@@ -623,14 +663,39 @@ def _pip_package_impl(ctx):
     version = ctx.attr.version
     license = ctx.attr.license
     pyproject_toml_file = ctx.actions.declare_file("%s/pyproject.toml" % STAGING_DIRECTORY_NAME)
+    entry_points = ""
+    for group, entries in ctx.attr.entry_points.items():
+        entry_points += "[project.entry-points.%s]\n" % group
+        for entry in entries:
+            name, separator, module = entry.partition("=")
+            if separator == "":
+                fail("Expected an entry_points entry of the form " +
+                     "'name = module', but got '%s'" % entry)
+            entry_points += '%s = "%s"\n' % (name.strip(), module.strip())
+
+    dynamic_fields = '["dependencies"]'
+    optional_dependencies = ""
+    if extras_requirements_txts:
+        dynamic_fields = '["dependencies", "optional-dependencies"]'
+        optional_dependencies = (
+            "[tool.setuptools.dynamic.optional-dependencies]\n"
+        )
+        for extra_name in extras_requirements_txts.keys():
+            optional_dependencies += (
+                '%s = { file = ["requirements-%s.txt"] }\n' %
+                (extra_name, extra_name)
+            )
     ctx.actions.expand_template(
         template = ctx.file._toml_template,
         output = pyproject_toml_file,
         substitutions = {
             "{CLASSIFIERS}": str(classifiers),
             "{DESCRIPTION}": ctx.attr.description,
+            "{DYNAMIC_FIELDS}": dynamic_fields,
+            "{ENTRY_POINTS}": entry_points,
             "{LICENSE}": license,
             "{NAME}": ctx.attr.distribution_name,
+            "{OPTIONAL_DEPENDENCIES}": optional_dependencies,
             "{PACKAGE_DATA}": package_data,
             "{SCRIPTS}": scripts,
             "{VERSION}": version,
@@ -711,8 +776,11 @@ def _pip_package_impl(ctx):
             output_directory,
             "--verify-python-version",
             ctx.attr._python_version,
-            "--requirements-txt",
-            staged_requirements_txt.path,
+        ] + [
+            "--requirements-txt=%s" % requirements.path
+            for requirements in (
+                [staged_requirements_txt] + staged_extras_requirements_txts
+            )
         ] + [
             "--verify-dependency-in-requirements=%s" % dependency
             for dependency in pypi_dependencies.keys()
@@ -768,6 +836,23 @@ _pip_package = rule(
             doc = "The name of the distribution to generate.",
             mandatory = True,
         ),
+        "entry_points": attr.string_list_dict(
+            default = {},
+            doc = "The entry points this pip package advertises: " +
+                  "each key is an entry-point group, e.g. " +
+                  "'pytest11', and each value that group's " +
+                  "'name = module' entries.",
+        ),
+        "extras": attr.label_keyed_string_dict(
+            allow_files = True,
+            default = {},
+            doc = "Optional-dependency extras: each key is a " +
+                  "requirements file and each value the extra's name; " +
+                  "the file's packages ship as that extra instead of " +
+                  "as dependencies, and every one of them must also " +
+                  "be in `requirements_txt`, which stays the " +
+                  "complete list.",
+        ),
         "license": attr.string(
             doc = "The license to use for the pip package.",
             mandatory = True,
@@ -823,6 +908,11 @@ _pip_package = rule(
             default = Label("//bazel/pip_package_rule:setup.py.template"),
             allow_single_file = True,
         ),
+        "_strip_requirements_tool": attr.label(
+            default = Label("//bazel/pip_package_rule:strip_requirements"),
+            executable = True,
+            cfg = "exec",
+        ),
         "_toml_template": attr.label(
             # A pointer to the template for the `pyproject.toml` file.
             default = Label("//bazel/pip_package_rule:pyproject.toml.template"),

bazel/pip_package_rule/pyproject.toml.template

@@ -3,7 +3,7 @@ name = "{NAME}"
 version = "{VERSION}"
 # TODO: See https://github.com/reboot-dev/mono/issues/4200.
 requires-python = ">=3.10,<3.13"
-dynamic = ["dependencies"]
+dynamic = {DYNAMIC_FIELDS}
 readme = "README.md"
 description = "{DESCRIPTION}"
 classifiers = {CLASSIFIERS}
@@ -12,13 +12,17 @@ license = "{LICENSE}"
 [tool.setuptools.dynamic]
 dependencies = { file = "requirements.txt" }
 
+{OPTIONAL_DEPENDENCIES}
+
 [build-system]
 requires = ["setuptools"]
 build-backend = "setuptools.build_meta"
 
 [project.scripts]
 {SCRIPTS}
 
+{ENTRY_POINTS}
+
 [tool.setuptools]
 # The default settings understand our `src/` layout and will auto-discover the
 # Python packages we've placed there. We don't need to specify them here.

bazel/pip_package_rule/strip_requirements.py

@@ -0,0 +1,85 @@
+"""Writes a requirements file with the packages of the given extras
+requirements files removed, so that those packages ship as a wheel's
+optional-dependency extras instead of its dependencies."""
+
+import argparse
+import re
+
+
+def normalize_package_name(name: str) -> str:
+    """
+    Normalizes the package name per
+    https://packaging.python.org/en/latest/specifications/name-normalization/#normalization
+    """
+    return re.sub(r"[-_.]+", "-", name).lower()
+
+
+def find_package_name(line: str) -> str:
+    """
+    Given a line like:
+    ```
+    my-cool_pAcKaG3.n4me==1.2.3 # some comment.
+    ```
+    Returns "my-cool.pAcKaG3.n4me".
+    """
+    package_name = re.match("^([\\w._-]+)", line, flags=re.IGNORECASE)
+    if package_name is None:
+        raise ValueError(f"Could not find package name in line: '{line}'")
+
+    return package_name.group(1)
+
+
+def requirement_packages(filename: str) -> set[str]:
+    """The normalized package names the requirements file pins."""
+    packages = set()
+    with open(filename) as requirements:
+        for line in requirements:
+            line = line.strip()
+            if not line or line.startswith("#"):
+                continue
+            packages.add(normalize_package_name(find_package_name(line)))
+    return packages
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--requirements-txt", type=str, required=True)
+    parser.add_argument("--output", type=str, required=True)
+    parser.add_argument(
+        "--extra-requirements-txt",
+        type=str,
+        action="append",
+        default=[],
+        help="requirements file whose packages become an extra, so "
+        "they are removed from the output; every one of its packages "
+        "must be present in --requirements-txt",
+    )
+    args = parser.parse_args()
+
+    extras_packages = set()
+    for filename in args.extra_requirements_txt:
+        extras_packages.update(requirement_packages(filename))
+
+    missing = extras_packages - requirement_packages(args.requirements_txt)
+    if missing:
+        raise ValueError(
+            f"Expected the extras packages {sorted(missing)} to also be "
+            f"in '{args.requirements_txt}', which stays the complete "
+            "list, but they were not"
+        )
+
+    with open(args.requirements_txt) as requirements:
+        with open(args.output, "w") as output:
+            for line in requirements:
+                stripped = line.strip()
+                if stripped and not stripped.startswith("#"):
+                    package = normalize_package_name(
+                        find_package_name(stripped)
+                    )
+                    if package in extras_packages:
+                        continue
+                output.write(line)
+
+
+if __name__ == "__main__":
+    main()

documentation/docs/learn_more/errors.mdx

@@ -215,10 +215,6 @@ Here's an example of how the `OverdraftError` can be caught in a type-safe way:
 
 <Tabs groupId="language">
   <TabItem value="python" label="Python" default>
-<!-- MARKDOWN-AUTO-DOCS:START
-(CODE:src=../../../reboot/examples/monorepo/bank/backend/tests/account_servicer_test.py&lines=51-61) -->
-<!-- The below code snippet is automatically added from ../../../reboot/examples/monorepo/bank/backend/tests/account_servicer_test.py -->
-
 ```py
 try:
     await account.withdraw(context, amount=65)
@@ -232,8 +228,6 @@ except Account.WithdrawAborted as aborted:
             )
     raise
 ```
-
-<!-- MARKDOWN-AUTO-DOCS:END -->
   </TabItem>
   <TabItem value="typescript" label="TypeScript">
 <!-- MARKDOWN-AUTO-DOCS:START

documentation/docs/learn_more/tasks.mdx

@@ -154,18 +154,12 @@ If all you have is a `TaskId`, you can use `retrieve()` to get a
 
 <Tabs groupId="language">
   <TabItem value="python" label="Python">
-<!-- MARKDOWN-AUTO-DOCS:START
-(CODE:src=../../../reboot/examples/monorepo/bank/backend/tests/account_servicer_test.py&lines=89-92) -->
-<!-- The below code snippet is automatically added from ../../../reboot/examples/monorepo/bank/backend/tests/account_servicer_test.py -->
-
 ```py
 response = await Account.WelcomeEmailTask.retrieve(
     context,
     task_id=welcome_email_task_id,
 )
 ```
-
-<!-- MARKDOWN-AUTO-DOCS:END -->
   </TabItem>
   <TabItem value="typescript" label="TypeScript">
 ```ts

documentation/docs/learn_more/testing.md

@@ -11,10 +11,6 @@ To write a test, you can use the `reboot.aio.tests.Reboot` class. This allows
 you to start your servicer, create a context, and call the method you want to
 test.
 
-<!-- MARKDOWN-AUTO-DOCS:START
-(CODE:src=../../../reboot/examples/chat-room/backend/tests/chat_room_servicer_test.py&lines=10-40) -->
-<!-- The below code snippet is automatically added from ../../../reboot/examples/chat-room/backend/tests/chat_room_servicer_test.py -->
-
 ```py
 async def asyncSetUp(self) -> None:
     self.rbt = Reboot()
@@ -48,8 +44,6 @@ async def test_chat_room(self) -> None:
     )
 ```
 
-<!-- MARKDOWN-AUTO-DOCS:END -->
-
 #### Setting Secrets
 
 Some servicers may use [secrets](/learn_more/secrets) for connecting