Kubernetes Type Stubs (Elephant Fork)

35.0.0.post1 · active · verified Thu Apr 16

This library provides type stubs for the official Kubernetes Python API client. It is an actively maintained fork of the original `kubernetes-stubs` package, offering static type checking support for projects using the `kubernetes` client. The current version is 35.0.0.post1, with a frequent release cadence aimed at keeping pace with upstream `kubernetes` client updates.

Common errors

```
ModuleNotFoundError: No module named 'kubernetes_stubs_elephant_fork'
```
cause You are attempting to import symbols directly from the stub package, which contains no runtime code.

fix Import symbols from the actual `kubernetes` client library (e.g., `from kubernetes import client`). The stub package is picked up automatically by type checkers for static analysis.
```
mypy: No library stub file for 'kubernetes.client'
```
cause `kubernetes-stubs-elephant-fork` is not installed, or its version is incompatible with your `kubernetes` client, or MyPy is not correctly configured.

fix Ensure `pip install kubernetes-stubs-elephant-fork` is run. Check the stub package's README for compatible `kubernetes` client versions and upgrade/downgrade if necessary. You might also try `mypy --verbose` to debug path issues.
```
mypy: Conflicting definitions for 'kubernetes.client'
```
cause You likely have both the original `kubernetes-stubs` and `kubernetes-stubs-elephant-fork` packages installed, leading to type checker confusion.

fix Uninstall the older or conflicting stub package. Run `pip uninstall kubernetes-stubs` to remove the unmaintained predecessor.

Warnings

gotcha The version number of `kubernetes-stubs-elephant-fork` does not directly correspond to the `kubernetes` client version it supports. For example, `kubernetes-stubs-elephant-fork==35.0.0.post1` targets `kubernetes>=28.0.0`. Always consult the stub package's README or changelog to confirm compatibility with your specific `kubernetes` client version to avoid unexpected type errors.
Fix: Refer to the `kubernetes-stubs-elephant-fork` GitHub README for the exact `kubernetes` client version range supported by your installed stub version.
gotcha `kubernetes-stubs-elephant-fork` contains only type stubs and is not meant for direct runtime import or execution. Attempting to `from kubernetes_stubs_elephant_fork import ...` will lead to a `ModuleNotFoundError` or similar runtime error.
Fix: Always import symbols from the actual `kubernetes` client library (e.g., `from kubernetes import client`). The stub package is automatically discovered by type checkers.
gotcha If migrating from the unmaintained original `kubernetes-stubs` package, it is crucial to uninstall it to prevent potential conflicts or incorrect stub resolution by your type checker.
Fix: Run `pip uninstall kubernetes-stubs` before or after installing `kubernetes-stubs-elephant-fork`.

Install

pip install kubernetes-stubs-elephant-fork Install package

Imports

client
```
from kubernetes import client
```
Type stubs are automatically picked up by type checkers (e.g., MyPy) for imports from the 'kubernetes' library. You do not import directly from 'kubernetes_stubs_elephant_fork' as it contains no runtime code.
config
wrong:
```
from kubernetes_stubs_elephant_fork import config
```
correct:
```
from kubernetes import config
```
Attempting to import from the stub package directly at runtime will result in a ModuleNotFoundError or similar, as it only contains type definitions, not executable code.

Quickstart

This quickstart demonstrates how `kubernetes-stubs-elephant-fork` provides type hints for code that uses the `kubernetes` client library. The stubs are automatically picked up by type checkers like MyPy, without requiring direct imports from the stub package. The `if __name__ == "__main__"` block provides a runnable example requiring Kubernetes connectivity.

import os
from kubernetes import client, config
from typing import TYPE_CHECKING

# This function will only execute at runtime, not during type checking
if not TYPE_CHECKING:
    # Load Kubernetes configuration
    # For local development, e.g., ~/.kube/config
    try:
        config.load_kube_config(context=os.environ.get('KUBE_CONTEXT', ''))
    except config.config_exception.ConfigException:
        # Fallback for CI/CD or in-cluster
        config.load_incluster_config()

def get_pod_names(namespace: str) -> list[str]:
    # The type checker uses kubernetes-stubs-elephant-fork here
    v1: client.CoreV1Api = client.CoreV1Api()
    
    # The return type of list_namespaced_pod is typed by the stubs
    pods_list = v1.list_namespaced_pod(namespace=namespace)
    
    names: list[str] = []
    for pod in pods_list.items:
        if pod.metadata and pod.metadata.name:
            names.append(pod.metadata.name)
    return names

if __name__ == "__main__":
    # Example runtime usage (requires a running Kubernetes cluster/config)
    try:
        # Replace 'default' with your target namespace or use env var
        target_namespace = os.environ.get('KUBE_NAMESPACE', 'default')
        pod_names = get_pod_names(target_namespace)
        print(f"Pods in '{target_namespace}' namespace: {pod_names}")
    except Exception as e:
        print(f"Could not list pods (is Kubernetes configured?): {e}")

# To type-check this file:
# 1. pip install mypy kubernetes kubernetes-stubs-elephant-fork
# 2. mypy quickstart.py

view raw JSON →