@@ -15,136 +15,159 @@ the Python-specific directives in use can be found in the
1515
1616The Python-specific directives are:
1717
18- * [ ` # gazelle:python_extension ` ] ( #python-extension )
18+ {.glossary}
19+ [ ` # gazelle:python_extension value ` ] ( #python-extension )
20+ : Controls whether the Python extension is enabled or not. Sub-packages
21+ inherit this value.
1922 * Default: ` enabled `
2023 * Allowed Values: ` enabled ` , ` disabled `
21- * Controls whether the Python extension is enabled or not. Sub-packages
22- inherit this value.
23- * [ ` # gazelle:python_root ` ] ( #python-root )
24+
25+ [ ` # gazelle:python_root ` ] ( #python-root )
26+ : Sets a Bazel package as a Python root. This is used on monorepos with
27+ multiple Python projects that don't share the top-level of the workspace
28+ as the root.
2429 * Default: n/a
2530 * Allowed Values: None. This direcive does not consume values.
26- * Sets a Bazel package as a Python root. This is used on monorepos with
27- multiple Python projects that don't share the top-level of the workspace
28- as the root.
29- * [ ` # gazelle:python_manifest_file_name ` ] ( #python-manifest-file-name )
31+
32+ [ ` # gazelle:python_manifest_file_name value ` ] ( #python-manifest-file-name )
33+ : Overrides the default manifest file name.
3034 * Default: ` gazelle_python.yaml `
3135 * Allowed Values: A string
32- * Overrides the default manifest file name.
33- * [ ` # gazelle:python_ignore_files ` ] ( #python-ignore-files )
36+
37+ [ ` # gazelle:python_ignore_files value ` ] ( #python-ignore-files )
38+ : Controls the files which are ignored from the generated targets.
3439 * Default: n/a
35- * Allowed Values: WIP
36- * Controls the files which are ignored from the generated targets.
37- * [ ` # gazelle:python_ignore_dependencies ` ] ( #python-ignore-dependencies )
40+ * Allowed Values: A comma-separated list of strings.
41+
42+ [ ` # gazelle:python_ignore_dependencies value ` ] ( #python-ignore-dependencies )
43+ : Controls the ignored dependencies from the generated targets.
3844 * Default: n/a
39- * Allowed Values: WIP
40- * Controls the ignored dependencies from the generated targets.
41- * [ ` # gazelle:python_validate_import_statements ` ] ( #python-validate-import-statements )
45+ * Allowed Values: A comma-separated list of strings.
46+
47+ [ ` # gazelle:python_validate_import_statements bool ` ] ( #python-validate-import-statements )
48+ : Controls whether the Python import statements should be validated.
4249 * Default: ` true `
4350 * Allowed Values: ` true ` , ` false `
44- * Controls whether the Python import statements should be validated.
45- * [ ` # gazelle:python_generation_mode ` ] ( #python-generation-mode )
51+
52+ [ ` # gazelle:python_generation_mode value ` ] ( #python-generation-mode )
53+ : Controls the target generation mode.
4654 * Default: ` package `
4755 * Allowed Values: ` file ` , ` package ` , ` project `
48- * Controls the target generation mode.
49- * [ ` # gazelle:python_generation_mode_per_file_include_init ` ] ( #python-generation-mode-per-file-include-init )
56+
57+ [ ` # gazelle:python_generation_mode_per_file_include_init bool ` ] ( #python-generation-mode-per-file-include-init )
58+ : Controls whether ` __init__.py ` files are included as srcs in each
59+ generated target when target generation mode is "file".
5060 * Default: ` false `
5161 * Allowed Values: ` true ` , ` false `
52- * Controls whether ` __init__.py ` files are included as srcs in each
53- generated target when target generation mode is "file".
54- * [ ` # gazelle:python_generation_mode_per_package_require_test_entry_point ` ] ( python-generation-mode-per-package-require-test-entry-point )
62+
63+ [ ` # gazelle:python_generation_mode_per_package_require_test_entry_point bool ` ] ( python-generation-mode-per-package-require-test-entry-point )
64+ : Controls whether a file called ` __test__.py ` or a target called
65+ ` __test__ ` is required to generate one test target per package in
66+ package mode.
5567 * Default: ` true `
5668 * Allowed Values: ` true ` , ` false `
57- * Controls whether a file called ` __test__.py ` or a target called
58- ` __test__ ` is required to generate one test target per package in
59- package mode.
60- * [ ` # gazelle:python_library_naming_convention ` ] ( #python-library-naming-convention )
69+
70+ [ ` # gazelle:python_library_naming_convention value ` ] ( #python-library-naming-convention )
71+ : Controls the {bzl: obj }` py_library ` naming convention. It interpolates
72+ ` $package_name$ ` with the Bazel package name. E.g. if the Bazel package
73+ name is ` foo ` , setting this to ` $package_name$_my_lib ` would result in a
74+ generated target named ` foo_my_lib ` .
6175 * Default: ` $package_name$ `
6276 * Allowed Values: A string containing ` "$package_name$" `
63- * Controls the {bzl: obj }` py_library ` naming convention. It interpolates
64- ` $package_name$ ` with the Bazel package name. E.g. if the Bazel package
65- name is ` foo ` , setting this to ` $package_name$_my_lib ` would result in a
66- generated target named ` foo_my_lib ` .
67- * [ ` # gazelle:python_binary_naming_convention ` ] ( #python-binary-naming-convention )
77+
78+ [ ` # gazelle:python_binary_naming_convention value ` ] ( #python-binary-naming-convention )
79+ : Controls the {bzl: obj }` py_binary ` naming convention. Follows the same interpolation
80+ rules as ` python_library_naming_convention ` .
6881 * Default: ` $package_name$_bin `
6982 * Allowed Values: A string containing ` "$package_name$" `
70- * Controls the {bzl: obj }` py_binary ` naming convention. Follows the same interpolation
71- rules as ` python_library_naming_convention ` .
72- * [ ` # gazelle:python_test_naming_convention ` ] ( #python-test-naming-convention )
83+
84+ [ ` # gazelle:python_test_naming_convention value ` ] ( #python-test-naming-convention )
85+ : Controls the {bzl: obj }` py_test ` naming convention. Follows the same interpolation
86+ rules as ` python_library_naming_convention ` .
7387 * Default: ` $package_name$_test `
7488 * Allowed Values: A string containing ` "$package_name$" `
75- * Controls the {bzl: obj }` py_test ` naming convention. Follows the same interpolation
76- rules as ` python_library_naming_convention ` .
77- * [ ` # gazelle:python_proto_naming_convention ` ] ( #python-proto-naming-convention )
89+
90+ [ ` # gazelle:python_proto_naming_convention value ` ] ( #python-proto-naming-convention )
91+ : Controls the {bzl: obj }` py_proto_library ` naming convention. It interpolates
92+ ` $proto_name$ ` with the {bzl: obj }` proto_library ` rule name, minus any trailing
93+ ` _proto ` . E.g. if the {bzl: obj }` proto_library ` name is ` foo_proto ` , setting this
94+ to ` $proto_name$_my_lib ` would render to ` foo_my_lib ` .
7895 * Default: ` $proto_name$_py_pb2 `
7996 * Allowed Values: A string containing ` "$proto_name$" `
80- * Controls the {bzl: obj }` py_proto_library ` naming convention. It interpolates
81- ` $proto_name$ ` with the {bzl: obj }` proto_library ` rule name, minus any trailing
82- ` _proto ` . E.g. if the {bzl: obj }` proto_library ` name is ` foo_proto ` , setting this
83- to ` $proto_name$_my_lib ` would render to ` foo_my_lib ` .
84- * [ ` # gazelle:resolve py ... ` ] ( #resolve-py )
97+
98+ [ ` # gazelle:resolve py import-lang import-string label ` ] ( #resolve-py )
99+ : Instructs the plugin what target to add as a dependency to satisfy a given
100+ import statement. The syntax is ` # gazelle:resolve py import-string label `
101+ where ` import-string ` is the symbol in the python ` import ` statement,
102+ and ` label ` is the Bazel label that Gazelle should write in ` deps ` .
85103 * Default: n/a
86104 * Allowed Values: See the [ bazel-gazelle docs] [ gazelle-directives ]
87- * Instructs the plugin what target to add as a dependency to satisfy a given
88- import statement. The syntax is ` # gazelle:resolve py import-string label `
89- where ` import-string ` is the symbol in the python ` import ` statement,
90- and ` label ` is the Bazel label that Gazelle should write in ` deps ` .
91- * [ ` # gazelle:python_default_visibility labels ` ] ( python-default-visibility )
105+
106+ [ ` # gazelle:python_default_visibility labels ` ] ( python-default-visibility )
107+ : Instructs gazelle to use these visibility labels on all python targets.
108+ ` labels ` is a comma-separated list of labels (without spaces).
92109 * Default: ` //$python_root$:__subpackages__ `
93110 * Allowed Values: A string
94- * Instructs gazelle to use these visibility labels on all python targets.
95- ` labels ` is a comma-separated list of labels (without spaces).
96- * [ ` # gazelle:python_visibility label ` ] ( python-visibility )
111+
112+ [ ` # gazelle:python_visibility label ` ] ( python-visibility )
113+ : Appends additional visibility labels to each generated target. This r
114+ directive can be set multiple times.
97115 * Default: n/a
98116 * Allowed Values: A string
99- * Appends additional visibility labels to each generated target. This r
100- directive can be set multiple times.
101- * [ ` # gazelle:python_test_file_pattern ` ] ( python-test-file-pattern )
117+
118+ [ ` # gazelle:python_test_file_pattern value ` ] ( python-test-file-pattern )
119+ : Filenames matching these comma-separated {command}` glob ` s will be mapped to
120+ {bzl: obj }` py_test ` targets.
102121 * Default: ` *_test.py,test_*.py `
103122 * Allowed Values: A glob string
104- * Filenames matching these comma-separated {command}` glob ` s will be mapped to
105- {bzl: obj }` py_test ` targets.
106- * [ ` # gazelle:python_label_convention ` ] ( #python-label-convention )
123+
124+ [ ` # gazelle:python_label_convention value ` ] ( #python-label-convention )
125+ : Defines the format of the distribution name in labels to third-party deps.
126+ Useful for using Gazelle plugin with other rules with different repository
127+ conventions (e.g. ` rules_pycross ` ). Full label is always prepended with
128+ the ` pip ` repository name, e.g. ` @pip//numpy ` if your
129+ ` MODULE.bazel ` has ` use_repo(pip, "pip") ` or ` @pypi//numpy `
130+ if your ` MODULE.bazel ` has ` use_repo(pip, "pypi") ` .
107131 * Default: ` $distribution_name$ `
108132 * Allowed Values: A string
109- * Defines the format of the distribution name in labels to third-party deps.
110- Useful for using Gazelle plugin with other rules with different repository
111- conventions (e.g. ` rules_pycross ` ). Full label is always prepended with
112- the ` pip ` repository name, e.g. ` @pip//numpy ` if your
113- ` MODULE.bazel ` has ` use_repo(pip, "pip") ` or ` @pypi//numpy `
114- if your ` MODULE.bazel ` has ` use_repo(pip, "pypi") ` .
115- * [ ` # gazelle:python_label_normalization ` ] ( #python-label-normalization )
133+
134+ [ ` # gazelle:python_label_normalization value ` ] ( #python-label-normalization )
135+ : Controls how distribution names in labels to third-party deps are
136+ normalized. Useful for using Gazelle plugin with other rules with different
137+ label conventions (e.g. ` rules_pycross ` uses PEP-503).
116138 * Default: ` snake_case `
117139 * Allowed Values: ` snake_case ` , ` none ` , ` pep503 `
118- * Controls how distribution names in labels to third-party deps are
119- normalized. Useful for using Gazelle plugin with other rules with different
120- label conventions (e.g. ` rules_pycross ` uses PEP-503).
121- * [ ` # gazelle:python_experimental_allow_relative_imports ` ] ( #python-experimental-allow- relative-imports )
140+
141+ [ ` # gazelle:python_experimental_allow_relative_imports bool ` ] ( #python-experimental-allow-relative-imports )
142+ : Controls whether Gazelle resolves dependencies for import statements that
143+ use paths relative to the current package.
122144 * Default: ` false `
123145 * Allowed Values: ` true ` , ` false `
124- * Controls whether Gazelle resolves dependencies for import statements that
125- use paths relative to the current package.
126- * [ ` # gazelle:python_generate_pyi_deps ` ] ( #python-generate-pyi-deps )
146+
147+ [ ` # gazelle:python_generate_pyi_deps bool ` ] ( #python-generate-pyi-deps )
148+ : Controls whether to generate a separate ` pyi_deps ` attribute for
149+ type-checking dependencies or merge them into the regular ` deps `
150+ attribute. When ` false ` (default), type-checking dependencies are
151+ merged into ` deps ` for backward compatibility. When ` true ` , generates
152+ separate ` pyi_deps ` . Imports in blocks with the format
153+ ` if typing.TYPE_CHECKING: ` or ` if TYPE_CHECKING: ` and type-only stub
154+ packages (eg. boto3-stubs) are recognized as type-checking dependencies.
127155 * Default: ` false `
128156 * Allowed Values: ` true ` , ` false `
129- * Controls whether to generate a separate ` pyi_deps ` attribute for
130- type-checking dependencies or merge them into the regular ` deps `
131- attribute. When ` false ` (default), type-checking dependencies are
132- merged into ` deps ` for backward compatibility. When ` true ` , generates
133- separate ` pyi_deps ` . Imports in blocks with the format
134- ` if typing.TYPE_CHECKING: ` or ` if TYPE_CHECKING: ` and type-only stub
135- packages (eg. boto3-stubs) are recognized as type-checking dependencies.
136- * [ ` # gazelle:python_generate_proto ` ] ( #python-generate-proto )
157+
158+ [ ` # gazelle:python_generate_proto bool ` ] ( #python-generate-proto )
159+ : Controls whether to generate a {bzl: obj }` py_proto_library ` for each
160+ {bzl: obj }` proto_library ` in the package. By default we load this rule from the
161+ ` @protobuf ` repository; use ` gazelle:map_kind ` if you need to load this
162+ from somewhere else.
137163 * Default: ` false `
138164 * Allowed Values: ` true ` , ` false `
139- * Controls whether to generate a {bzl: obj }` py_proto_library ` for each
140- {bzl: obj }` proto_library ` in the package. By default we load this rule from the
141- ` @protobuf ` repository; use ` gazelle:map_kind ` if you need to load this
142- from somewhere else.
143- * [ ` # gazelle:python_resolve_sibling_imports ` ] ( #python-resolve-sibling-imports )
165+
166+ [ ` # gazelle:python_resolve_sibling_imports bool ` ] ( #python-resolve-sibling-imports )
167+ : Allows absolute imports to be resolved to sibling modules (Python 2's
168+ behavior without ` absolute_import ` ).
144169 * Default: ` false `
145170 * Allowed Values: ` true ` , ` false `
146- * Allows absolute imports to be resolved to sibling modules (Python 2's
147- behavior without ` absolute_import ` ).
148171
149172
150173## ` python_extension `
0 commit comments