portforward 0.7.3__cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

portforward/__init__.py

@@ -0,0 +1,253 @@
+"""
+Easy Kubernetes Port-Forward For Python
+"""
+
+__version__ = "0.7.3"
+
+import asyncio
+import contextlib
+import ipaddress
+import os
+from enum import Enum
+from pathlib import Path
+from typing import Generator, Optional, Union
+
+from portforward import _portforward
+
+
+class PortforwardError(Exception):
+    """Will be raised when something went wrong while the port-forward process."""
+
+
+class LogLevel(Enum):
+    DEBUG = 0
+    INFO = 1
+    WARN = 2
+    ERROR = 3
+    OFF = 4
+
+
+@contextlib.contextmanager
+def forward(
+    namespace: str,
+    pod_or_service: str,
+    from_port: int,
+    to_port: int,
+    config_path: Optional[str] = None,
+    waiting: float = 0.1,
+    log_level: LogLevel = LogLevel.INFO,
+    kube_context: str = "",
+    bind_ip: Union[ipaddress.IPv4Address, ipaddress.IPv6Address, str, None] = None,
+) -> Generator["PortForwarder", None, None]:
+    """
+    Connects to a **pod or service** and tunnels traffic from a local port to
+    this target. It uses the kubectl kube config from the home dir if no path
+    is provided.
+
+    The libary will figure out for you if it has to target a pod or service.
+
+    It will fall back to in-cluster-config in case no kube config file exists.
+
+    (Best consumed as context manager.)
+
+    Example:
+        >>> import portforward
+        >>> with portforward.forward("test", "web-svc", 9000, 80):
+        >>>     # Do work
+
+    :param namespace: Target namespace
+    :param pod_or_service: Name of target Pod or service
+    :param from_port: Local port, or 0 to use any free port
+    :param to_port: Port inside the pod
+    :param config_path: Path for loading kube config
+    :param waiting: Delay in seconds
+    :param log_level: Level of logging
+    :param kube_context: Target kubernetes context (fallback is current context)
+    :param bind_ip: To which IP shall the portforward be bind
+    :return: forwarder to manual stop the forwarding
+    """
+
+    forwarder = PortForwarder(
+        namespace,
+        pod_or_service,
+        from_port,
+        to_port,
+        config_path,
+        waiting,
+        log_level,
+        kube_context,
+        bind_ip,
+    )
+
+    try:
+        forwarder.forward()
+
+        yield forwarder
+
+    except RuntimeError as err:
+        # Suppress extension exception
+        raise PortforwardError(err) from None
+
+    finally:
+        forwarder.stop()
+
+
+class PortForwarder:
+    """Use the same args as the `portforward.forward` method."""
+
+    def __init__(
+        self,
+        namespace: str,
+        pod_or_service: str,
+        from_port: int,
+        to_port: int,
+        config_path: Optional[str] = None,
+        waiting: float = 0.1,
+        log_level: LogLevel = LogLevel.INFO,
+        kube_context: str = "",
+        bind_ip: Union[ipaddress.IPv4Address, ipaddress.IPv6Address, str, None] = None,
+    ) -> None:
+        self._async_forwarder = AsyncPortForwarder(
+            namespace,
+            pod_or_service,
+            from_port,
+            to_port,
+            config_path,
+            waiting,
+            log_level,
+            kube_context,
+            bind_ip,
+        )
+
+    def forward(self):
+        asyncio.run(self._async_forwarder.forward())
+
+    def stop(self):
+        asyncio.run(self._async_forwarder.stop())
+
+    @property
+    def is_stopped(self):
+        return self._async_forwarder.is_stopped
+
+    @property
+    def from_port(self):
+        """The local port that was actually used for the portforward."""
+        return self._async_forwarder.from_port
+
+
+class AsyncPortForwarder:
+    """Use the same args as the `portforward.forward` method."""
+
+    def __init__(
+        self,
+        namespace: str,
+        pod_or_service: str,
+        from_port: int,
+        to_port: int,
+        config_path: Optional[str] = None,
+        waiting: float = 0.1,
+        log_level: LogLevel = LogLevel.INFO,
+        kube_context: str = "",
+        bind_ip: Union[ipaddress.IPv4Address, ipaddress.IPv6Address, str, None] = None,
+    ) -> None:
+        self.namespace: str = _validate_str("namespace", namespace)
+        self.pod_or_service: str = _validate_str("pod_or_service", pod_or_service)
+        self.to_port: int = _validate_port("to_port", to_port)
+        self.log_level: LogLevel = _validate_log(log_level)
+        self.waiting: float = waiting
+
+        self.config_path: str = _config_path(config_path)
+        self.kube_context: str = _kube_context(kube_context)
+
+        _validate_port("from_port", from_port)
+        bind_ip = _validate_ip_address(bind_ip)
+
+        self.actual_pod_name: str = ""
+        self.from_port: int = 0
+        self._is_stopped: bool = False
+        self.bind_address: str = f"{bind_ip}:{from_port}"
+
+    async def forward(self):
+        (self.actual_pod_name, self.from_port) = await _portforward.forward(
+            self.namespace,
+            self.pod_or_service,
+            self.bind_address,
+            self.to_port,
+            self.config_path,
+            self.log_level.value,
+            self.kube_context,
+        )
+        self._is_stopped = False
+
+    async def stop(self):
+        await _portforward.stop(
+            self.namespace, self.actual_pod_name, self.to_port, self.log_level.value
+        )
+        self._is_stopped = True
+
+    def is_stopped(self):
+        return self._is_stopped
+
+
+# ===== PRIVATE =====
+
+
+def _validate_str(arg_name, arg) -> str:
+    if arg is None or not isinstance(arg, str):
+        raise ValueError(f"{arg_name}={arg} is not a valid str")
+
+    if len(arg) == 0:
+        raise ValueError(f"{arg_name} cannot be an empty str")
+
+    return arg
+
+
+def _validate_port(arg_name, arg) -> int:
+    in_range = arg is not None and 0 <= arg < 65536
+    if arg is None or not isinstance(arg, int) or not in_range:
+        raise ValueError(f"{arg_name}={arg} is not a valid port")
+
+    return arg
+
+
+def _validate_log(log_level):
+    if not isinstance(log_level, LogLevel):
+        raise ValueError(f"log_level={log_level} is not a valid LogLevel")
+
+    return log_level
+
+
+def _validate_ip_address(ip_address):
+    if not ip_address:
+        return "127.0.0.1"
+
+    if isinstance(ip_address, ipaddress.IPv4Address) or isinstance(
+        ip_address, ipaddress.IPv4Address
+    ):
+        return str(ip_address)
+
+    return str(ipaddress.ip_address(ip_address))
+
+
+def _config_path(config_path_arg) -> str:
+    if config_path_arg and not isinstance(config_path_arg, str):
+        raise ValueError(f"config_path={config_path_arg} is not a valid str")
+
+    elif config_path_arg:
+        return config_path_arg
+
+    alt_path = str(Path.home() / ".kube" / "config")
+
+    config_path = os.environ.get("KUBECONFIG", alt_path)
+
+    return config_path if os.path.isfile(config_path) else ""
+
+
+def _kube_context(context):
+    if not context:
+        return ""
+
+    if not isinstance(context, str):
+        raise ValueError(f"kube_context={context} is not a valid str")
+
+    return context

portforward/_portforward.pyi

@@ -0,0 +1,17 @@
+"""
+Rust native module / Python C Extension
+"""
+
+async def forward(
+    namespace: str,
+    pod_or_service: str,
+    bind_address: str,
+    to_port: int,
+    config_path: str,
+    log_level: int,
+    kube_context: str,
+) -> None:
+    pass
+
+async def stop(namespace: str, actual_pod: str, to_port: int, log_level: int) -> None:
+    pass

portforward-0.7.3.dist-info/METADATA

@@ -0,0 +1,138 @@
+Metadata-Version: 2.4
+Name: portforward
+Version: 0.7.3
+Classifier: Programming Language :: Rust
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+License-File: LICENSE
+License-File: AUTHORS.rst
+Summary: Easy Kubernetes Port-Forward For Python
+Keywords: portforward,kubernetes,k8s
+Author-email: Sebastian Ziemann <corka149@mailbox.org>
+License: MIT License
+Requires-Python: >=3.7
+Description-Content-Type: text/x-rst; charset=UTF-8
+Project-URL: Documentation, https://portforward.readthedocs.io
+Project-URL: Repository, https://github.com/pytogo/portforward.git
+Project-URL: Changelog, https://github.com/pytogo/portforward/blob/main/HISTORY.rst
+
+===========
+portforward
+===========
+
+
+.. image:: https://img.shields.io/pypi/v/portforward.svg
+        :target: https://pypi.python.org/pypi/portforward
+
+.. image:: https://img.shields.io/pypi/status/portforward.svg
+        :target: https://pypi.python.org/pypi/portforward
+
+.. image:: https://img.shields.io/pypi/dm/portforward
+        :alt: PyPI - Downloads
+
+.. image:: https://readthedocs.org/projects/portforward/badge/?version=latest
+        :target: https://portforward.readthedocs.io/en/latest/?version=latest
+        :alt: Documentation Status
+
+.. image:: https://github.com/pytogo/portforward/actions/workflows/python-app.yml/badge.svg
+        :target: https://github.com/pytogo/portforward/actions
+        :alt: Build status
+
+
+
+Easy Kubernetes Port-Forward For Python
+
+
+* Free software: MIT license
+* Documentation: https://portforward.readthedocs.io.
+
+
+Installation
+-----------------------------
+
+Wheels are available for:
+
+* **Windows** (architectures: ``x64``, ``x86``)
+* **macOS**   (architectures: ``x86_64``, ``aarch64``)
+* **Linux**   (architectures: ``x86_64``, ``x86``, ``aarch64``, ``armv7``, ``s390x``, ``ppc64le``)
+
+Musllinux wheels (Alpine‑compatible) are provided for ``x86_64``, ``x86``, ``aarch64`` and ``armv7``.
+
+with Python versions:
+
+* 3.9
+* 3.10
+* 3.11
+* 3.12
+* 3.13
+
+**Requirements for installation from source**
+
+The following things are required when there is no wheel available for the target system.
+
+* `Rust` installed and available in the path (https://www.rust-lang.org/tools/install)
+* `Python` (at least v3.7 - below was never tested but might work)
+
+Pip knows how to install ``portforward``.
+
+.. code-block::
+
+    pip install portforward
+
+
+Quickstart
+----------
+
+.. code-block:: Python
+
+    import requests
+
+    import portforward
+
+
+    def main():
+        namespace = "test"
+        pod_name = "web"  # You can also use a service name instead
+        local_port = 9000  # from port
+        pod_port = 80  # to port
+
+        # No path to kube config provided - will use default from $HOME/.kube/config
+        with portforward.forward(namespace, pod_name, local_port, pod_port):
+            response = requests.get("http://localhost:9000")
+            print(f"Done: \n'{response.status_code}'\n'{response.text[:20]}...'")
+
+
+    if __name__ == "__main__":
+        main()
+
+
+Features
+--------
+
+* Native Kubernetes port-forwarding with the ``.kube/config`` from the home dir
+  or any other path to config.
+* Portforward for pods and services - the lib will first look for a pod with matching name then for
+  a service
+* Waiting for a pod to become ready
+* Multiple forwards per pod or service
+* As context manager, sync or async client
+
+
+Development
+-----------
+
+In case you want to develop on this library itself please take a look at the CONTRIBUTING page.
+
+Credits
+-------
+
+This project is enabled by PyO3_.
+
+.. _PyO3: https://pyo3.rs
+

portforward-0.7.3.dist-info/RECORD

@@ -0,0 +1,9 @@
+portforward-0.7.3.dist-info/METADATA,sha256=Wd7jjideXh0I793Cl3OIZ5klfMP0F61XnQHIyy3u82w,3916
+portforward-0.7.3.dist-info/WHEEL,sha256=91qjQrS97zMh9AkI-A3VvdI6WJJUiA4S51adLZexhzo,131
+portforward-0.7.3.dist-info/licenses/LICENSE,sha256=n2aq0UH0YZkyF_5hougjNi5gzXIUapEEqEUn6FwAcFE,1075
+portforward-0.7.3.dist-info/licenses/AUTHORS.rst,sha256=YQwE3_FUEuGVHbxYUa4NQMlG28QBGwcCYEoa2MP9Xgk,163
+portforward/_portforward.pyi,sha256=KZSR_2INAUDtpwbVFA9e6cLs3KBwgMw-hgtirmMRZgY,336
+portforward/__init__.py,sha256=sys9oCQQ2o2z6HcyEo3ioPhgvxQ6oVn3BP5nS0G5Qf0,6872
+portforward/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+portforward/_portforward.cpython-313-aarch64-linux-gnu.so,sha256=Yv58jgvDognysHEjGZfvvkf4AVbDp_CmrIqxTAir550,15533248
+portforward-0.7.3.dist-info/RECORD,,

portforward-0.7.3.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: maturin (1.8.3)
+Root-Is-Purelib: false
+Tag: cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64

portforward-0.7.3.dist-info/licenses/AUTHORS.rst

@@ -0,0 +1,13 @@
+=======
+Credits
+=======
+
+Development Lead
+----------------
+
+* Sebastian Ziemann <corka149@mailbox.org>
+
+Contributors
+------------
+
+None yet. Why not be the first?

portforward-0.7.3.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021, Sebastian Ziemann
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.