feat!: Following generation mode when generating test targets

[linzhp]

When python_generation_mode is project or file , the generated py_test targets are consistent with py_library. However, when python_generation_mode is package, it becomes inconsistent: it requires either __test__ target or __test__.py file to generate py_test in package mode, otherwise it will fall back to file mode.

This PR relaxes this requirement with a new directive gazelle:python_generation_mode_per_package_require_test_entry_point. Whent it's set to false, Gazelle and generates one py_test target per package in package mode even without entry points.

This allows people to use gazelle:map_kind to map py_test to a macro that sets a default test runner, such as rules_python_pytest or pytest-bazel, and generate one test target per package. The behavior when gazelle:python_generation_mode is "file" or "project" remains the same.

This fixes #1972 for supporting pytest from Gazelle. With this approach, people can define a thin macro like this to use py_pytest_main:

load("@aspect_rules_py//py:defs.bzl", "py_pytest_main")

def py_test(name, **kwargs):
    py_pytest_main(
        name = "__test__",
        deps = ["@pip_pytest//:pkg"],  # change this to the pytest target in your repo.
    )

    deps = kwargs.pop("deps", [])
    deps.append(":__test__")

    py_test(
        name = name,
        main = ":__test__.py",
        deps = deps,
        **kwargs,
)

BREAKING CHANGES:
Without gazelle:map_kind or __test__ target or __test__.py, the package mode will now generate py_test without main attribute, which may not be runnable. However, this is already an issue with "python_generation_mode:project" before this PR.

The default value of gazelle:python_generation_mode_per_package_require_test_entry_point is true to preserve the current behavior. We will flip that default value in the future.

[aignas]

In order for this to be mergeable we should be the policy outlined here: https://rules-python.readthedocs.io/en/latest/contributing.html#breaking-changes

So we should go with the approach of an extra directive, which we may later set to default to some other value than today. Maybe it could default to file as it is today or am I missing something here?

[linzhp]

Added the directive and updated readme to include the macro. Please take another look

[aignas]

LGTM, added a CHANGELOG entry for a future release announcement.