Nest async client under kubernetes.aio to fix kubernetes-asyncio collision

[karimzakzouk]

What type of PR is this?

/kind bug

What this PR does / why we need it:

Right now, setup-release.py installs the new async client as a top-level package called kubernetes_asyncio. The problem is that this directly collides with the existing kubernetes-asyncio package on PyPI. When people try to install both, they overwrite each other's files and break.

This PR fixes that by nesting the async client under kubernetes.aio instead (using setuptools package_dir). This matches what other big libraries do (like redis.asyncio or grpc.aio) and cleanly avoids the naming collision.

The main changes:

• Updated setup-release.py to map the package to kubernetes.aio
• Switched the absolute imports in kubernetes_asyncio/ to relative imports so the code works whether it's installed via the release bundle or as a standalone package for dev.
• Added a simple try/except in kubernetes/__init__.py to optionally expose the aio module.
• Updated the examples to use the new kubernetes.aio import path.

Which issue(s) this PR fixes:

Fixes #2583

Special notes for your reviewer:

Most of the files changed here are just bulk mechanical fixes (switching from kubernetes_asyncio.client... to relative imports) across the code.

The actual logic changes are pretty small and isolated to setup-release.py, the two __init__.py files, and api_client.py.

Note: We'll probably want to update the OpenAPI generator templates in a follow-up PR to spit out relative imports by default for future generation runs.

Does this PR introduce a user-facing change?

The bundled async client is now available at `kubernetes.aio` instead of `kubernetes_asyncio` to prevent overwriting the external `kubernetes-asyncio` package on PyPI. If you were using the new async client from v36.0.0, please update your imports from `from kubernetes_asyncio import client` to `from kubernetes.aio import client`.

Additional documentation e.g., KEPs (Kubernetes Enhancement Proposals), usage docs, etc.:

NONE

[k8s-ci-robot]

Welcome @karimzakzouk!

It looks like this is your first PR to kubernetes-client/python 🎉. Please refer to our pull request process documentation to help your PR have a smooth ride to approval.

You will be prompted by a bot to use commands during the review process. Do not be afraid to follow the prompts! It is okay to experiment. Here is the bot commands documentation.

You can also check if kubernetes-client/python has its own contribution guidelines.

You may want to refer to our testing guide if you run into trouble with your tests not passing.

If you are having difficulty getting your pull request seen, please follow the recommended escalation practices. Also, for tips and tricks in the contribution process you may want to read the Kubernetes contributor cheat sheet. We want to make sure your contribution gets all the attention it needs!

Thank you, and welcome to Kubernetes. 😃

[Copilot]

Copilot wasn't able to review this pull request because it exceeds the maximum number of files (300). Try reducing the number of changed files and requesting a review from Copilot again.

[roycaihw]

/assign @yliaog

[yliaog]

@karimzakzouk thanks for the PR, many files in this repo are generated, it is better to fix it in the script generator.

I created a PR #2590 to switch from kubernetes_asyncio to kuberentes_aio to avoid the conflict. Please take a look.

[karimzakzouk]

@yliaog That makes perfect sense, fixing it directly in the generator scripts is the right move. Thanks for the comment

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: karimzakzouk
Once this PR has been reviewed and has the lgtm label, please ask for approval from yliaog. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[karimzakzouk]

@yliaog Following up on your comment. Yes, I agree we should fix it in the generator scripts, so I updated this PR to do exactly that.

I also added a script to scripts/update-client-asyncio.sh. It automatically changes all the absolute imports to relative imports right after the generation finishes.
I left a comment on #2590 to explain how this solves the namespace issue as kubernetes.aio, while keeping the repository directory clean and flat for us.

All tests pass locally. Please take a look.

[yliaog]

@karimzakzouk I think it is better for the synchronous and asyncio clients to use similar import path, say, one uses kubernetes.client, the other uses kubernetes.aio.client. we can discuss switching to relative imports with the community, for both sync and asyncio clients. For now, I think it is fine to nest the whole async client under kubernetes/aio/ directory.