Better 111 support (#230)

Author: simontoens

CLAUDE.md

@@ -13,9 +13,9 @@ For verification of all code changes made, always run:
 The command above should complete without errors.
 Note that it isn't necessary to run bazel test on individual targets targets since the codebase is small - for simplicity just always use `bazel test //...`.
 
-`bazel run //:gen -- --package examples --destdir tests/examples_goldfiles`
+`rm -rf tests/examples_goldfiles/examples && bazel run //:gen -- --package examples --destdir tests/examples_goldfiles`
 The command above should complete without errors
-There should be no diffs un the tests/examples_goldfiles directory
+There should be no diffs under the tests/examples_goldfiles/examples directory
 
 `ruff check src tests misc`
 The command above should complete without errors

MODULE.bazel.lock

@@ -1,16 +1,48 @@
-# 111
+# 1:1:1
 
-This example shows that a Python project may be organized using Bazel's [1:1:1](https://bazel.build/basics/dependencies#using_fine-grained_modules_and_the_111_rule) rule.
+This example shows a Python project using Bazel's [1:1:1](https://bazel.build/basics/dependencies#using_fine-grained_modules_and_the_111_rule) structure of "one BUILD file per Bazel package". Why is this interesting? Because the `1:1:1` structure is a common layout when using Bazel, especially when using [Gazelle](https://github.com/bazel-contrib/bazel-gazelle) to generate BUILD files. However, when generating manifests and artifacts for a package manager, we typically do not want to generate at the granularity of the Bazel package level but instead at the "project level" - Poppy handles this translation.
 
-Note that this works well for Python projects because the wheel file construction is external to Bazel. On the other hand, this doesn't work well for Java based projects because the jar file building is done by Bazel (and so with 1:1:1 we'd end up with too many jar files - they would have to be merged into a single jar before being uploaded to the package manager).
 
+## Looking around
 
-## The pyproject.toml file
+This example consists of 2 libraries, [communicator](communicator) and [computer](computer).
+- `communicator` - has modules [phone](communicator/phone) and [caller](communicator/caller). The phone module has [111 mode enabled](communicator/phone/md/pyproject.in): `generation_mode` is set to `dynamic_111`. The `caller` module depends on the `phone` module.
+- `computer` - has modules [amiga](computer/amiga) and [user](computer/user). Both modules have 111 mode enabled. The `user` module depends on the `amiga` module.
+- Library dependencies: `communicator` depends on `computer`; this link exists bcause `phone` depends on `amiga` [here](communicator/phone/src/phone/emulator/BUILD).
 
-Run this command:
+The following `poppy` command shows how both libraries are related:
 
 ```
-bazel run @poppy//package/py -- -l examples/python/111 -a gen
+bazel run //:query -- --package examples/python/111/communicator --library_release_plan_tree
+
+examples/python/111/communicator ++ 2.0.1
+  examples/python/111/computer ++ 1.0.1
+
+++ artifact has never been released
+```
+
+
+## About 1:1:1 mode
+
+Support for `1:1:1` package structure must be set explicitly in the manifest file: `generation_mode = "dynamic_111"` [example](communicator/phone/md/pyproject.in).
+Additionally, the manifest file must specify an "aggregation" target that has as dependencies all child `1:1:1` targets, in that example linked below that is configured by `target_name = "venv"`. For Python, this works well with a `venv` target. Note that if the `venv` target includes tests, those should be excluded explicitly (in the linked example, that is done using `excluded_dependency_paths = ["tests"]`.
+Finally, the module structure must follow the modern Python project structure with top level `src` and `tests` directories.
+
+
+## The 1:1:1 manifest
+
+The generated manifest (pyproject.toml) aggregates all dependencies from child Bazel packages if they are:
+- External (pip) dependencies
+- Source dependencies that point outside of the 1:1:1 module
+
+As an example, generate the `communicator` library manifest files:
+
 ```
+bazel run //:gen -- --package examples/python/111/communicator --destdir /tmp/py
+```
+
+Since `communicator` depends on `computer`, and each library has 2 modules, 4 manifests are generated.
+
+The `communicator/phone` manifest at `/tmp/py/examples/python/111/communicator/phone/pyproject.toml` lists these dependencies:
 
-Note [111_mode is enabled](md/pyproject.in) and that the child Bazel packages do not define any Poppy related metadata - dependencies declared in child Bazel packages' BUILD.bazel files are "pushed up" to, and included in, the `pyproject.toml` file generated for the `111` project.
+- `uvicorn[standard]>=0.34.0` brought in through [communicator/phone/src/phone/ringtone/BUILD](communicator/phone/src/phone/ringtone/BUILD)

examples/python/111/BUILD

@@ -0,0 +1,8 @@
+load("@aspect_rules_py//py:defs.bzl", "py_binary")
+
+
+py_binary(
+    name = "caller",
+    srcs = ["main.py",],
+    deps = ["//examples/python/111/communicator/phone/src/phone"],
+)

examples/python/111/README.md

@@ -0,0 +1,14 @@
+import mobile
+
+
+def run():
+    # let's make a call
+    for event in mobile.make_outbound_call():
+        print(event)
+
+    # start the amiga emulator to play lemmings
+    mobile.run_amiga_emulator()
+
+
+if __name__ == "__main__":
+    run()

examples/python/111/communicator/caller/BUILD

@@ -0,0 +1,10 @@
+artifact(
+    artifact_id = "caller",
+    version = "2.0.1",
+    generation_mode = "dynamic",
+    excluded_dependency_paths = ["tests"],
+)
+
+artifact_update(
+    version_increment_strategy = "minor",
+)

examples/python/111/communicator/caller/main.py

@@ -0,0 +1,15 @@
+load("@aspect_rules_py//py:defs.bzl", "py_venv")
+
+
+py_venv(
+    name = "venv",
+    testonly = True,
+    deps = [
+        "//examples/python/111/communicator/phone/src/phone",
+        "//examples/python/111/communicator/phone/src/phone/emulator",
+        "//examples/python/111/communicator/phone/src/phone/message",
+        "//examples/python/111/communicator/phone/src/phone/ringtone",
+        "//examples/python/111/communicator/phone/tests",
+    ],
+)
+

examples/python/111/communicator/caller/md/pyproject.in

@@ -0,0 +1,11 @@
+artifact(
+    artifact_id = "phone",
+    version = "2.0.1",
+    generation_mode = "dynamic_111",
+    target_name = "venv",
+    excluded_dependency_paths = ["tests"],
+)
+
+artifact_update(
+    version_increment_strategy = "minor",
+)