Skip to content

docs(gazelle): Migrate Gazelle docs to ReadTheDocs, part 3/5: annotations #3137

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Aug 4, 2025
Merged

docs(gazelle): Migrate Gazelle docs to ReadTheDocs, part 3/5: annotations #3137

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
5b61b03
docs(gazelle): Migrate Gazelle docs to ReadTheDocs, part 3/5: annotat…
dougthor42 Aug 1, 2025
a088594
versionadded
dougthor42 Aug 4, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
185 changes: 0 additions & 185 deletions gazelle/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:

```
<target> 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
Expand Down
194 changes: 194 additions & 0 deletions gazelle/docs/annotations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,194 @@
# 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:

```
<target> 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`

:::{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
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
Copy link
Collaborator

@aignas aignas Aug 4, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Consider using versionadded directive.

See https://github.com/search?q=repo%3Abazel-contrib%2Frules_python+versionadded&type=code for examples

Copy link
Collaborator Author

@dougthor42 dougthor42 Aug 4, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah, I'd forgotten about that directive!

I updated Added in PR 3080 to use it but I opted to keep this one as-is because

  1. I wanted to keep both the version and PR links and
  2. I thought that it would be confusing to see "Added in version 0.14.0" under the include_pytest_conftest section.


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.
1 change: 1 addition & 0 deletions gazelle/docs/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,4 +43,5 @@ the `update` command (the default) does anything for Python code.
```{toctree}
:maxdepth: 1
installation_and_usage
annotations
```