kr8s.asyncio
============

.. py:module:: kr8s.asyncio

.. autoapi-nested-parse::

   The `kr8s` asynchronous API.

   This module provides an asynchronous API for interacting with a Kubernetes cluster.



Submodules
----------

.. toctree::
   :maxdepth: 1

   /autoapi/kr8s/asyncio/objects/index
   /autoapi/kr8s/asyncio/portforward/index


Classes
-------

.. autoapisummary::

   kr8s.asyncio.Api


Functions
---------

.. autoapisummary::

   kr8s.asyncio.api
   kr8s.asyncio.api_resources
   kr8s.asyncio.create
   kr8s.asyncio.get
   kr8s.asyncio.version
   kr8s.asyncio.watch
   kr8s.asyncio.whoami


Package Contents
----------------

.. py:class:: Api(**kwargs)

   A kr8s object for interacting with the Kubernetes API.

   .. warning::
       This class is not intended to be instantiated directly. Instead, use the
       :func:`kr8s.api` function to get a singleton instance of the API.

       See https://docs.kr8s.org/en/stable/client.html#client-caching.



   .. py:attribute:: auth


   .. py:property:: timeout


   .. py:method:: call_api(method: str = 'GET', version: str = 'v1', base: str = '', namespace: str | None = None, url: str = '', raise_for_status: bool = True, stream: bool = False, **kwargs) -> collections.abc.AsyncGenerator[httpx.Response]
      :async:


      Make a Kubernetes API request.



   .. py:method:: open_websocket(version: str = 'v1', base: str = '', namespace: str | None = None, url: str = '', **kwargs) -> collections.abc.AsyncGenerator[httpx_ws.AsyncWebSocketSession]
      :async:


      Open a websocket connection to a Kubernetes API endpoint.



   .. py:method:: version() -> dict
      :async:


      Get the Kubernetes version information from the API.

      Returns:
          The Kubernetes version information.




   .. py:method:: async_version() -> dict
      :async:



   .. py:method:: reauthenticate() -> None
      :async:


      Reauthenticate the API.



   .. py:method:: async_reauthenticate() -> None
      :async:



   .. py:method:: whoami()
      :async:


      Retrieve the subject that's currently authenticated.

      Inspired by `kubectl whoami`.

      Returns:
          str: The subject that's currently authenticated.



   .. py:method:: async_whoami()
      :async:



   .. py:method:: lookup_kind(kind) -> tuple[str, str, bool]
      :async:


      Lookup a Kubernetes resource kind.

      Check whether a resource kind exists on the remote server.

      Args:
          kind: The kind of resource to lookup.

      Returns:
          The kind of resource, the plural form and whether the resource is namespaced

      Raises:
          ValueError: If the kind is not found.



   .. py:method:: async_lookup_kind(kind, skip_cache: bool = False) -> tuple[str, str, bool]
      :async:


      Lookup a Kubernetes resource kind.



   .. py:method:: async_get_kind(kind: str | type[kr8s._objects.APIObject], namespace: str | None = None, label_selector: str | dict | None = None, field_selector: str | dict | None = None, params: dict | None = None, watch: bool = False, allow_unknown_type: bool = True, **kwargs) -> collections.abc.AsyncGenerator[tuple[type[kr8s._objects.APIObject], httpx.Response]]
      :async:


      Get a Kubernetes resource.



   .. py:method:: get(kind: str | type, *names: str, namespace: str | None = None, label_selector: str | dict | None = None, field_selector: str | dict | None = None, as_object: type[kr8s._objects.APIObject] | None = None, allow_unknown_type: bool = True, raw: bool = False, **kwargs) -> collections.abc.AsyncGenerator[kr8s._objects.APIObject | dict]
      :async:


      Get Kubernetes resources.

      Args:
          kind: The kind of resource to get.
          *names: The names of specific resources to get.
          namespace: The namespace to get the resource from.
          label_selector: The label selector to filter the resources by.
          field_selector: The field selector to filter the resources by.
          as_object: The object to return the resources as.
          allow_unknown_type: Automatically create a class for the resource if none exists, default True.
          raw: If True, return raw dictionaries instead of APIObject instances, default False.
          **kwargs: Additional keyword arguments to pass to the API call.

      Returns:
          The resources.



   .. py:method:: async_get(kind: str | type, *names: str, namespace: str | None = None, label_selector: str | dict | None = None, field_selector: str | dict | None = None, as_object: type[kr8s._objects.APIObject] | None = None, allow_unknown_type: bool = True, raw: bool = False, **kwargs) -> collections.abc.AsyncGenerator[kr8s._objects.APIObject | dict]
      :async:



   .. py:method:: watch(kind: str, namespace: str | None = None, label_selector: str | dict | None = None, field_selector: str | dict | None = None, since: str | None = None) -> collections.abc.AsyncGenerator[tuple[str, kr8s._objects.APIObject]]
      :async:


      Watch a Kubernetes resource.



   .. py:method:: async_watch(kind: str, namespace: str | None = None, label_selector: str | dict | None = None, field_selector: str | dict | None = None, since: str | None = None, allow_unknown_type: bool = True) -> collections.abc.AsyncGenerator[tuple[str, kr8s._objects.APIObject]]
      :async:


      Watch a Kubernetes resource.



   .. py:method:: api_resources() -> list[dict]
      :async:


      Get the Kubernetes API resources.



   .. py:method:: async_api_resources() -> list[dict]
      :async:



   .. py:method:: async_api_resources_uncached() -> list[dict]
      :async:


      Get the Kubernetes API resources.



   .. py:method:: api_versions() -> collections.abc.AsyncGenerator[str]
      :async:


      Get the Kubernetes API versions.



   .. py:method:: async_api_versions() -> collections.abc.AsyncGenerator[str]
      :async:



   .. py:method:: async_create(resources: list[kr8s._objects.APIObject])
      :async:



   .. py:method:: create(resources: list[kr8s._objects.APIObject])
      :async:



   .. py:property:: namespace
      :type: str


      Get the default namespace.



.. py:function:: api(url: Optional[str] = None, kubeconfig: Optional[str] = None, serviceaccount: Optional[str] = None, namespace: Optional[str] = None, context: Optional[str] = None, _asyncio: bool = True) -> kr8s._api.Api
   :async:


   Create a `kr8s.asyncio.Api` object for interacting with the Kubernetes API.

   If a kr8s object already exists with the same arguments in this thread, it will be returned.

   Args:
       url: The URL of the Kubernetes API server
       kubeconfig: The path to a kubeconfig file to use
       serviceaccount: The path of a service account to use
       namespace: The namespace to use
       context: The context to use

   Returns:
       kr8s.asyncio.Api: The API object

   Examples:
       >>> import kr8s
       >>> api = await kr8s.asyncio.api()  # Uses the default kubeconfig
       >>> print(await api.version())  # Get the Kubernetes version


.. py:function:: api_resources(api=None, _asyncio=True)
   :async:


.. py:function:: create(resources: list[kr8s._objects.APIObject], api=None, _asyncio=True)
   :async:


   Create resources in the Kubernetes cluster.


.. py:function:: get(kind: str, *names: str, namespace: Optional[str] = None, label_selector: Optional[Union[str, dict]] = None, field_selector: Optional[Union[str, dict]] = None, as_object: Optional[type[kr8s._objects.APIObject]] = None, allow_unknown_type: bool = True, raw: bool = False, api=None, _asyncio=True, **kwargs)
   :async:


   Get a resource by name.

   This function retrieves a resource from the Kubernetes cluster based on its kind and name(s).
   It supports various options for filtering and customization.

   Args:
       kind: The kind of resource to get.
       *names: The names of the resources to get.
       namespace: The namespace to get the resource from.
       label_selector: The label selector to filter the resources by.
       field_selector: The field selector to filter the resources by.
       as_object: The object to populate with the resource data.
       allow_unknown_type: Automatically create a class for the resource if none exists.
       raw: If True, return raw dictionaries instead of APIObject instances, default False.
       api: The api to use to get the resource.
       **kwargs: Additional keyword arguments to pass to the `httpx` API call.

   Returns:
       List[APIObject]: The Kubernetes resource objects (or dicts if raw=True).

   Raises:
       ValueError: If the resource is not found.

   Examples:
       >>> import kr8s
       >>> # All of these are equivalent
       >>> ings = await kr8s.asyncio.get("ing")                           # Short name
       >>> ings = await kr8s.asyncio.get("ingress")                       # Singular
       >>> ings = await kr8s.asyncio.get("ingresses")                     # Plural
       >>> ings = await kr8s.asyncio.get("Ingress")                       # Title
       >>> ings = await kr8s.asyncio.get("ingress.networking.k8s.io")     # Full group name
       >>> ings = await kr8s.asyncio.get("ingress.v1.networking.k8s.io")  # Full with explicit version
       >>> ings = await kr8s.asyncio.get("ingress.networking.k8s.io/v1")  # Full with explicit version alt.
       >>>
       >>> # Get raw dictionaries for better performance
       >>> pods = [pod async for pod in kr8s.asyncio.get("pods", raw=True)]
       >>> print(pods[0]["metadata"]["name"])


.. py:function:: version(api=None, _asyncio=True)
   :async:


.. py:function:: watch(kind: str, namespace: Optional[str] = None, label_selector: Optional[Union[str, dict]] = None, field_selector: Optional[Union[str, dict]] = None, since: Optional[str] = None, api=None, _asyncio=True)
   :async:


.. py:function:: whoami(api=None, _asyncio=True)
   :async: