From 5b61b0325db2c1fcc92ea45cadb1857045160787 Mon Sep 17 00:00:00 2001 From: Douglas Thor Date: Thu, 31 Jul 2025 20:23:57 -0700 Subject: [PATCH 1/2] docs(gazelle): Migrate Gazelle docs to ReadTheDocs, part 3/5: annotations --- gazelle/README.md | 185 ---------------------------------- gazelle/docs/annotations.md | 192 ++++++++++++++++++++++++++++++++++++ gazelle/docs/index.md | 1 + 3 files changed, 193 insertions(+), 185 deletions(-) create mode 100644 gazelle/docs/annotations.md diff --git a/gazelle/README.md b/gazelle/README.md index 11a9e5b2ba..efc7004eaf 100644 --- a/gazelle/README.md +++ b/gazelle/README.md @@ -390,191 +390,6 @@ py_proto_library( When `false`, Gazelle will ignore any `py_proto_library`, including previously-generated or hand-created rules. -### Annotations - -*Annotations* refer to comments found _within Python files_ that configure how -Gazelle acts for that particular file. - -Annotations have the form: - -```python -# gazelle:annotation_name value -``` - -and can reside anywhere within a Python file where comments are valid. For example: - -```python -import foo -# gazelle:annotation_name value - -def bar(): # gazelle:annotation_name value - pass -``` - -The annotations are: - -| **Annotation** | **Default value** | -|---------------------------------------------------------------|-------------------| -| [`# gazelle:ignore imports`](#annotation-ignore) | N/A | -| Tells Gazelle to ignore import statements. `imports` is a comma-separated list of imports to ignore. | | -| [`# gazelle:include_dep targets`](#annotation-include_dep) | N/A | -| Tells Gazelle to include a set of dependencies, even if they are not imported in a Python module. `targets` is a comma-separated list of target names to include as dependencies. | | -| [`# gazelle:include_pytest_conftest bool`](#annotation-include_pytest_conftest) | N/A | -| Whether or not to include a sibling `:conftest` target in the deps of a `py_test` target. Default behaviour is to include `:conftest`. | | - - -#### Annotation: `ignore` - -This annotation accepts a comma-separated string of values. Values are names of Python -imports that Gazelle should _not_ include in target dependencies. - -The annotation can be added multiple times, and all values are combined and -de-duplicated. - -For `python_generation_mode = "package"`, the `ignore` annotations -found across all files included in the generated target are removed from `deps`. - -Example: - -```python -import numpy # a pypi package - -# gazelle:ignore bar.baz.hello,foo -import bar.baz.hello -import foo - -# Ignore this import because _reasons_ -import baz # gazelle:ignore baz -``` - -will cause Gazelle to generate: - -```starlark -deps = ["@pypi//numpy"], -``` - - -#### Annotation: `include_dep` - -This annotation accepts a comma-separated string of values. Values _must_ -be Python targets, but _no validation is done_. If a value is not a Python -target, building will result in an error saying: - -``` - does not have mandatory providers: 'PyInfo' or 'CcInfo' or 'PyInfo'. -``` - -Adding non-Python targets to the generated target is a feature request being -tracked in [Issue #1865](https://github.com/bazel-contrib/rules_python/issues/1865). - -The annotation can be added multiple times, and all values are combined -and de-duplicated. - -For `python_generation_mode = "package"`, the `include_dep` annotations -found across all files included in the generated target are included in `deps`. - -Example: - -```python -# gazelle:include_dep //foo:bar,:hello_world,//:abc -# gazelle:include_dep //:def,//foo:bar -import numpy # a pypi package -``` - -will cause Gazelle to generate: - -```starlark -deps = [ - ":hello_world", - "//:abc", - "//:def", - "//foo:bar", - "@pypi//numpy", -] -``` - -#### Annotation: `include_pytest_conftest` - -Added in [#3080][gh3080]. - -[gh3080]: https://github.com/bazel-contrib/rules_python/pull/3080 - -This annotation accepts any string that can be parsed by go's -[`strconv.ParseBool`][ParseBool]. If an unparsable string is passed, the -annotation is ignored. - -[ParseBool]: https://pkg.go.dev/strconv#ParseBool - -Starting with [`rules_python` 0.14.0][rules-python-0.14.0] (specifically [PR #879][gh879]), -Gazelle will include a `:conftest` dependency to an `py_test` target that is in -the same directory as `conftest.py`. - -[rules-python-0.14.0]: https://github.com/bazel-contrib/rules_python/releases/tag/0.14.0 -[gh879]: https://github.com/bazel-contrib/rules_python/pull/879 - -This annotation allows users to adjust that behavior. To disable the behavior, set -the annotation value to "false": - -``` -# some_file_test.py -# gazelle:include_pytest_conftest false -``` - -Example: - -Given a directory tree like: - -``` -. -├── BUILD.bazel -├── conftest.py -└── some_file_test.py -``` - -The default Gazelle behavior would create: - -```starlark -py_library( - name = "conftest", - testonly = True, - srcs = ["conftest.py"], - visibility = ["//:__subpackages__"], -) - -py_test( - name = "some_file_test", - srcs = ["some_file_test.py"], - deps = [":conftest"], -) -``` - -When `# gazelle:include_pytest_conftest false` is found in `some_file_test.py` - -```python -# some_file_test.py -# gazelle:include_pytest_conftest false -``` - -Gazelle will generate: - -```starlark -py_library( - name = "conftest", - testonly = True, - srcs = ["conftest.py"], - visibility = ["//:__subpackages__"], -) - -py_test( - name = "some_file_test", - srcs = ["some_file_test.py"], -) -``` - -See [Issue #3076][gh3076] for more information. - -[gh3076]: https://github.com/bazel-contrib/rules_python/issues/3076 - #### Directive: `python_experimental_allow_relative_imports` Enables experimental support for resolving relative imports in diff --git a/gazelle/docs/annotations.md b/gazelle/docs/annotations.md new file mode 100644 index 0000000000..b8652e0a15 --- /dev/null +++ b/gazelle/docs/annotations.md @@ -0,0 +1,192 @@ +# Annotations + +*Annotations* refer to comments found _within Python files_ that configure how +Gazelle acts for that particular file. + +Annotations have the form: + +```python +# gazelle:annotation_name value +``` + +and can reside anywhere within a Python file where comments are valid. For example: + +```python +import foo +# gazelle:annotation_name value + +def bar(): # gazelle:annotation_name value + pass +``` + +The annotations are: + +* [`# gazelle:ignore imports`](#ignore) + * Default: n/a + * Allowed Values: A comma-separated string of python package names + * Tells Gazelle to ignore import statements. `imports` is a comma-separated + list of imports to ignore. +* [`# gazelle:include_dep targets`](#include-dep) + * Default: n/a + * Allowed Values: A string + * Tells Gazelle to include a set of dependencies, even if they are not imported + in a Python module. `targets` is a comma-separated list of target names + to include as dependencies. +* [`# gazelle:include_pytest_conftest bool`](#include-pytest-conftest) + * Default: n/a + * Allowed Values: `true`, `false` + * Whether or not to include a sibling `:conftest` target in the `deps` + of a {bzl:obj}`py_test` target. The default behaviour is to include `:conftest` + (i.e.: `# gazelle:include_pytest_conftest true`). + + +## `ignore` + +This annotation accepts a comma-separated string of values. Values are names of +Python imports that Gazelle should _not_ include in target dependencies. + +The annotation can be added multiple times, and all values are combined and +de-duplicated. + +For `python_generation_mode = "package"`, the `ignore` annotations +found across all files included in the generated target are removed from +`deps`. + +### Example: + +```python +import numpy # a pypi package + +# gazelle:ignore bar.baz.hello,foo +import bar.baz.hello +import foo + +# Ignore this import because _reasons_ +import baz # gazelle:ignore baz +``` + +will cause Gazelle to generate: + +```starlark +deps = ["@pypi//numpy"], +``` + + +## `include_dep` + +This annotation accepts a comma-separated string of values. Values _must_ +be Python targets, but _no validation is done_. If a value is not a Python +target, building will result in an error saying: + +``` + does not have mandatory providers: 'PyInfo' or 'CcInfo' or 'PyInfo'. +``` + +Adding non-Python targets to the generated target is a feature request being +tracked in {gh-issue}`1865`. + +The annotation can be added multiple times, and all values are combined +and de-duplicated. + +For `python_generation_mode = "package"`, the `include_dep` annotations +found across all files included in the generated target are included in +`deps`. + +### Example: + +```python +# gazelle:include_dep //foo:bar,:hello_world,//:abc +# gazelle:include_dep //:def,//foo:bar +import numpy # a pypi package +``` + +will cause Gazelle to generate: + +```starlark +deps = [ + ":hello_world", + "//:abc", + "//:def", + "//foo:bar", + "@pypi//numpy", +] +``` + + +## `include_pytest_conftest` + +Added in {gh-pr}`3080`. + +This annotation accepts any string that can be parsed by go's +[`strconv.ParseBool`][ParseBool]. If an unparsable string is passed, the +annotation is ignored. + +[ParseBool]: https://pkg.go.dev/strconv#ParseBool + +Starting with [`rules_python` 0.14.0][rules-python-0.14.0] (specifically +{gh-pr}`879`), Gazelle will include a `:conftest` dependency to a +{bzl:obj}`py_test` target that is in the same directory as `conftest.py`. + +[rules-python-0.14.0]: https://github.com/bazel-contrib/rules_python/releases/tag/0.14.0 + +This annotation allows users to adjust that behavior. To disable the behavior, +set the annotation value to `false`: + +``` +# some_file_test.py +# gazelle:include_pytest_conftest false +``` + +### Example: + +Given a directory tree like: + +``` +. +├── BUILD.bazel +├── conftest.py +└── some_file_test.py +``` + +The default Gazelle behavior would create: + +```starlark +py_library( + name = "conftest", + testonly = True, + srcs = ["conftest.py"], + visibility = ["//:__subpackages__"], +) + +py_test( + name = "some_file_test", + srcs = ["some_file_test.py"], + deps = [":conftest"], +) +``` + +When `# gazelle:include_pytest_conftest false` is found in +`some_file_test.py` + +```python +# some_file_test.py +# gazelle:include_pytest_conftest false +``` + +Gazelle will generate: + +```starlark +py_library( + name = "conftest", + testonly = True, + srcs = ["conftest.py"], + visibility = ["//:__subpackages__"], +) + +py_test( + name = "some_file_test", + srcs = ["some_file_test.py"], +) +``` + +See {gh-issue}`3076` for more information. diff --git a/gazelle/docs/index.md b/gazelle/docs/index.md index c04efd6a41..e262d7ff46 100644 --- a/gazelle/docs/index.md +++ b/gazelle/docs/index.md @@ -43,4 +43,5 @@ the `update` command (the default) does anything for Python code. ```{toctree} :maxdepth: 1 installation_and_usage +annotations ``` From a08859465fe2b121c767b1ff4f99ebbd4517efe6 Mon Sep 17 00:00:00 2001 From: Douglas Thor Date: Mon, 4 Aug 2025 16:47:15 +0000 Subject: [PATCH 2/2] versionadded --- gazelle/docs/annotations.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/gazelle/docs/annotations.md b/gazelle/docs/annotations.md index b8652e0a15..cc87543c29 100644 --- a/gazelle/docs/annotations.md +++ b/gazelle/docs/annotations.md @@ -115,7 +115,9 @@ deps = [ ## `include_pytest_conftest` -Added in {gh-pr}`3080`. +:::{versionadded} VERSION_NEXT_FEATURE +{gh-pr}`3080` +::: This annotation accepts any string that can be parsed by go's [`strconv.ParseBool`][ParseBool]. If an unparsable string is passed, the