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

.. py:module:: kr8s.asyncio.portforward

.. autoapi-nested-parse::

   Objects for managing a port forward connection.

   This module provides a class for managing a port forward connection to a Kubernetes Pod or Service.



Classes
-------

.. autoapisummary::

   kr8s.asyncio.portforward.PortForward


Module Contents
---------------

.. py:class:: PortForward(resource: kr8s._objects.APIObject, remote_port: int, local_port: LocalPortType = 'match', address: list[str] | str = '127.0.0.1')

   Start a tcp server and forward all connections to a Pod port.

   You can either pass a :class:`kr8s.objects.Pod` or any resource with a ``ready_pods`` method
   such as a :class:`kr8s.objects.Service`.

   .. note::
       The ``ready_pods`` method should return a list of Pods that are ready to accept connections.

   .. warning:
       Currently Port Forwards only work when using ``asyncio`` and not ``trio``.

   Args:
       resource:
           The Pod or Resource to forward to.
       remote_port:
           The port on the Pod to forward to.
       local_port:
           The local port to listen on. Defaults to ``"match"``, which will match the ``remote_port``.
           Set to ``"auto"`` or ``None`` to find an available high port.
           Set to an ``int`` to specify a specific port.
       address:
           List of addresses or address to listen on. Defaults to ["127.0.0.1"], will listen only on 127.0.0.1.

   Example:
       This class can be used as a an async context manager or with explicit start/stop methods.

       Context manager:

       >>> async with PortForward(pod, 8888) as port:
       ...     print(f"Forwarding to port {port}")
       ...     # Do something with port 8888 on the Pod


       Explict start/stop:

       >>> pf = PortForward(pod, 8888)
       >>> await pf.start()
       >>> print(f"Forwarding to port {pf.local_port}")
       >>> # Do something with port 8888 on the Pod
       >>> await pf.stop()

       Explict bind address:

       >>> async with PortForward(pod, 8888, address=["127.0.0.1", "10.20.0.1"]) as port:
       ...     print(f"Forwarding to port {port}")
       ...     # Do something with port 8888 on the Pod, port will be bind to 127.0.0.1 and 10.20.0.1



   .. py:attribute:: server
      :value: None



   .. py:attribute:: servers
      :type:  list[asyncio.Server]
      :value: []



   .. py:attribute:: remote_port


   .. py:attribute:: address
      :value: '127.0.0.1'



   .. py:attribute:: pod
      :value: None



   .. py:method:: start() -> int
      :async:


      Start a background task with the port forward running.



   .. py:method:: async_start() -> int
      :async:



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


      Stop the background task.



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



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


      Run the port forward forever.

      Example:
          >>> pf = pod.portforward(remote_port=8888, local_port=8889)
          >>> # or
          >>> pf = PortForward(pod, remote_port=8888, local_port=8889)
          >>> await pf.run_forever()



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