docs: using python_version attribute for specifying python version (#2589)

Updates examples and docs to tell to use the base rules and the
python_version attribute
instead of the wrapper transition rules.

Author: JeroenSchmidt

CHANGELOG.md

@@ -62,6 +62,7 @@ Unreleased changes template.
 
 {#v0-0-0-fixed}
 ### Fixed
+* (docs) Using `python_version` attribute for specifying python versions introduced in `v1.1.0`
 * (gazelle) Providing multiple input requirements files to `gazelle_python_manifest` now works correctly.
 * (pypi) Handle trailing slashes in pip index URLs in environment variables,
   fixes [#2554](https://github.com/bazelbuild/rules_python/issues/2554).

docs/_includes/py_console_script_binary.md

@@ -12,7 +12,8 @@ py_console_script_binary(
 )
 ```
 
-Or for more advanced setups you can also specify extra dependencies and the
+#### Specifying extra dependencies 
+You can also specify extra dependencies and the
 exact script name you want to call. It is useful for tools like `flake8`, `pylint`,
 `pytest`, which have plugin discovery methods and discover dependencies from the
 PyPI packages available in the `PYTHONPATH`.
@@ -34,17 +35,26 @@ py_console_script_binary(
 )
 ```
 
-A specific Python version can be forced by using the generated version-aware
-wrappers, e.g. to force Python 3.9:
+#### Using a specific Python version
+
+A specific Python version can be forced by passing the desired Python version, e.g. to force Python 3.9:
 ```starlark
-load("@python_versions//3.9:defs.bzl", "py_console_script_binary")
+load("@rules_python//python/entry_points:py_console_script_binary.bzl", "py_console_script_binary")
 
 py_console_script_binary(
     name = "yamllint",
     pkg = "@pip//yamllint",
+    python_version = "3.9"
 )
 ```
 
+#### Using a specific Python Version directly from a Toolchain
+:::{deprecated} 1.1.0
+The toolchain specific `py_binary` and `py_test` symbols are aliases to the regular rules. 
+i.e. Deprecated `load("@python_versions//3.11:defs.bzl", "py_binary")` and `load("@python_versions//3.11:defs.bzl", "py_test")`
+
+You should instead specify the desired python version with `python_version`; see above example.
+:::
 Alternatively, the [`py_console_script_binary.binary_rule`] arg can be passed
 the version-bound `py_binary` symbol, or any other `py_binary`-compatible rule
 of your choosing:
@@ -60,5 +70,4 @@ py_console_script_binary(
 ```
 
 [specification]: https://packaging.python.org/en/latest/specifications/entry-points/
-[`py_console_script_binary.binary_rule`]: #py_console_script_binary_binary_rule
-
+[`py_console_script_binary.binary_rule`]: #py_console_script_binary_binary_rule

docs/toolchains.md

@@ -116,9 +116,9 @@ python = use_extension("@rules_python//python/extensions:python.bzl", "python")
 python.toolchain(python_version = "3.12")
 
 # BUILD.bazel
-load("@python_versions//3.12:defs.bzl", "py_binary")
+load("@rules_python//python:py_binary.bzl", "py_binary")
 
-py_binary(...)
+py_binary(..., python_version="3.12")
 ```
 
 ### Pinning to a Python version
@@ -132,21 +132,59 @@ is most useful for two cases:
    typically in a mono-repo situation.
 
 To configure a submodule with the version-aware rules, request the particular
-version you need, then use the `@python_versions` repo to use the rules that
-force specific versions:
+version you need when defining the toolchain:
 
 ```starlark
+# MODULE.bazel
 python = use_extension("@rules_python//python/extensions:python.bzl", "python")
 
 python.toolchain(
     python_version = "3.11",
 )
-use_repo(python, "python_versions")
+use_repo(python)
+```
+
+Then use the `@rules_python` repo in your BUILD file to explicity pin the Python version when calling the rule:
+
+```starlark
+# BUILD.bazel
+load("@rules_python//python:py_binary.bzl", "py_binary")
+
+py_binary(..., python_version = "3.11")
+py_test(..., python_version = "3.11")
 ```
 
-Then use e.g. `load("@python_versions//3.11:defs.bzl", "py_binary")` to use
-the rules that force that particular version. Multiple versions can be specified
-and use within a single build.
+Multiple versions can be specified and used within a single build.
+
+```starlark
+# MODULE.bazel
+python = use_extension("@rules_python//python/extensions:python.bzl", "python")
+
+python.toolchain(
+    python_version = "3.11",
+    is_default = True,
+)
+
+python.toolchain(
+    python_version = "3.12",
+)
+
+# BUILD.bazel
+load("@rules_python//python:py_binary.bzl", "py_binary")
+load("@rules_python//python:py_test.bzl", "py_test")
+
+# Defaults to 3.11
+py_binary(...)
+py_test(...)
+
+# Explicitly use Python 3.11
+py_binary(..., python_version = "3.11")
+py_test(..., python_version = "3.11")
+
+# Explicitly use Python 3.12
+py_binary(..., python_version = "3.12")
+py_test(..., python_version = "3.12")
+```
 
 For more documentation, see the bzlmod examples under the {gh-path}`examples`
 folder.  Look for the examples that contain a `MODULE.bazel` file.
@@ -159,6 +197,16 @@ The `python.toolchain()` call makes its contents available under a repo named
 Remember to call `use_repo()` to make repos visible to your module:
 `use_repo(python, "python_3_11")`
 
+
+:::{deprecated} 1.1.0
+The toolchain specific `py_binary` and `py_test` symbols are aliases to the regular rules. 
+i.e. Deprecated `load("@python_versions//3.11:defs.bzl", "py_binary")` & `load("@python_versions//3.11:defs.bzl", "py_test")`
+
+Usages of them should be changed to load the regular rules directly; 
+i.e.  Use `load("@rules_python//python:py_binary.bzl", "py_binary")` & `load("@rules_python//python:py_test.bzl", "py_test")` and then specify the `python_version` when using the rules corresponding to the python version you defined in your toolchain. {ref}`Library modules with version constraints`
+:::
+
+
 #### Toolchain usage in other rules
 
 Python toolchains can be utilized in other bazel rules, such as `genrule()`, by
@@ -508,4 +556,4 @@ of available toolchains.
 Currently the following flags are used to influence toolchain selection:
 * {obj}`--@rules_python//python/config_settings:py_linux_libc` for selecting the Linux libc variant.
 * {obj}`--@rules_python//python/config_settings:py_freethreaded` for selecting
-  the freethreaded experimental Python builds available from `3.13.0` onwards.
+  the freethreaded experimental Python builds available from `3.13.0` onwards.