Merge branch 'main' into fix.py_runtime.missing_attrs

Author: aignas

CHANGELOG.md

@@ -105,6 +105,9 @@ END_UNRELEASED_TEMPLATE
 
 {#v0-0-0-added}
 ### Added
+* (repl) Default stub now has tab completion, where `readline` support is available,
+  see ([#3114](https://github.com/bazel-contrib/rules_python/pull/3114)). 
+  ([#3114](https://github.com/bazel-contrib/rules_python/pull/3114)). 
 * (pypi) To configure the environment for `requirements.txt` evaluation, use the newly added
   developer preview of the `pip.default` tag class. Only `rules_python` and root modules can use
   this feature. You can also configure custom `config_settings` using `pip.default`.

gazelle/README.md

@@ -6,145 +6,6 @@ ReadTheDocs. Please see https://rules-python.readthedocs.io/gazelle/docs/index.h
 :::
 
 
-## Example
-
-We have an example of using Gazelle with Python located [here](https://github.com/bazel-contrib/rules_python/tree/main/examples/bzlmod).
-A fully-working example without using bzlmod is in [`examples/build_file_generation`](../examples/build_file_generation).
-
-The following documentation covers using bzlmod.
-
-## Adding Gazelle to your project
-
-First, you'll need to add Gazelle to your `MODULE.bazel` file.
-Get the current version of Gazelle from there releases here:  https://github.com/bazelbuild/bazel-gazelle/releases/.
-
-
-See the installation `MODULE.bazel` snippet on the Releases page:
-https://github.com/bazel-contrib/rules_python/releases in order to configure rules_python.
-
-You will also need to add the `bazel_dep` for configuration for `rules_python_gazelle_plugin`.
-
-Here is a snippet of a `MODULE.bazel` file.
-
-```starlark
-# The following stanza defines the dependency rules_python.
-bazel_dep(name = "rules_python", version = "0.22.0")
-
-# The following stanza defines the dependency rules_python_gazelle_plugin.
-# For typical setups you set the version.
-bazel_dep(name = "rules_python_gazelle_plugin", version = "0.22.0")
-
-# The following stanza defines the dependency gazelle.
-bazel_dep(name = "gazelle", version = "0.31.0", repo_name = "bazel_gazelle")
-
-# Import the python repositories generated by the given module extension into the scope of the current module.
-use_repo(python, "python3_9")
-use_repo(python, "python3_9_toolchains")
-
-# Register an already-defined toolchain so that Bazel can use it during toolchain resolution.
-register_toolchains(
-    "@python3_9_toolchains//:all",
-)
-
-# Use the pip extension
-pip = use_extension("@rules_python//python:extensions.bzl", "pip")
-
-# Use the extension to call the `pip_repository` rule that invokes `pip`, with `incremental` set.
-# Accepts a locked/compiled requirements file and installs the dependencies listed within.
-# Those dependencies become available in a generated `requirements.bzl` file.
-# You can instead check this `requirements.bzl` file into your repo.
-# Because this project has different requirements for windows vs other
-# operating systems, we have requirements for each.
-pip.parse(
-    name = "pip",
-    requirements_lock = "//:requirements_lock.txt",
-    requirements_windows = "//:requirements_windows.txt",
-)
-
-# Imports the pip toolchain generated by the given module extension into the scope of the current module.
-use_repo(pip, "pip")
-```
-Next, we'll fetch metadata about your Python dependencies, so that gazelle can
-determine which package a given import statement comes from. This is provided
-by the `modules_mapping` rule. We'll make a target for consuming this
-`modules_mapping`, and writing it as a manifest file for Gazelle to read.
-This is checked into the repo for speed, as it takes some time to calculate
-in a large monorepo.
-
-Gazelle will walk up the filesystem from a Python file to find this metadata,
-looking for a file called `gazelle_python.yaml` in an ancestor folder of the Python code.
-Create an empty file with this name. It might be next to your `requirements.txt` file.
-(You can just use `touch` at this point, it just needs to exist.)
-
-To keep the metadata updated, put this in your `BUILD.bazel` file next to `gazelle_python.yaml`:
-
-```starlark
-load("@pip//:requirements.bzl", "all_whl_requirements")
-load("@rules_python_gazelle_plugin//manifest:defs.bzl", "gazelle_python_manifest")
-load("@rules_python_gazelle_plugin//modules_mapping:def.bzl", "modules_mapping")
-
-# This rule fetches the metadata for python packages we depend on. That data is
-# required for the gazelle_python_manifest rule to update our manifest file.
-modules_mapping(
-    name = "modules_map",
-    wheels = all_whl_requirements,
-)
-
-# Gazelle python extension needs a manifest file mapping from
-# an import to the installed package that provides it.
-# This macro produces two targets:
-# - //:gazelle_python_manifest.update can be used with `bazel run`
-#   to recalculate the manifest
-# - //:gazelle_python_manifest.test is a test target ensuring that
-#   the manifest doesn't need to be updated
-gazelle_python_manifest(
-    name = "gazelle_python_manifest",
-    modules_mapping = ":modules_map",
-    # This is what we called our `pip_parse` rule, where third-party
-    # python libraries are loaded in BUILD files.
-    pip_repository_name = "pip",
-    # This should point to wherever we declare our python dependencies
-    # (the same as what we passed to the modules_mapping rule in WORKSPACE)
-    # This argument is optional. If provided, the `.test` target is very
-    # fast because it just has to check an integrity field. If not provided,
-    # the integrity field is not added to the manifest which can help avoid
-    # merge conflicts in large repos.
-    requirements = "//:requirements_lock.txt",
-    # include_stub_packages: bool (default: False)
-    # If set to True, this flag automatically includes any corresponding type stub packages
-    # for the third-party libraries that are present and used. For example, if you have
-    # `boto3` as a dependency, and this flag is enabled, the corresponding `boto3-stubs`
-    # package will be automatically included in the BUILD file.
-    #
-    # Enabling this feature helps ensure that type hints and stubs are readily available
-    # for tools like type checkers and IDEs, improving the development experience and
-    # reducing manual overhead in managing separate stub packages.
-    include_stub_packages = True
-)
-```
-
-Finally, you create a target that you'll invoke to run the Gazelle tool
-with the rules_python extension included. This typically goes in your root
-`/BUILD.bazel` file:
-
-```starlark
-load("@bazel_gazelle//:def.bzl", "gazelle")
-
-# Our gazelle target points to the python gazelle binary.
-# This is the simple case where we only need one language supported.
-# If you also had proto, go, or other gazelle-supported languages,
-# you would also need a gazelle_binary rule.
-# See https://github.com/bazelbuild/bazel-gazelle/blob/master/extend.rst#example
-gazelle(
-    name = "gazelle",
-    gazelle = "@rules_python_gazelle_plugin//python:gazelle_binary",
-)
-```
-
-That's it, now you can finally run `bazel run //:gazelle` anytime
-you edit Python code, and it should update your `BUILD` files correctly.
-
-
 ### Directives
 
 You can configure the extension using directives, just like for other
@@ -529,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