README.md

kubernetes-typed

mypy plugin to dynamically define types for Kubernetes objects.

Features

• Type checking for Custom Resources
• Type checking for kubernetes-client

Installation

Install with pip:

pip install kubernetes-typed

Versioning

This package follows kubernetes client versioning approach. MAJOR.MINOR parts of version will match client version for which stubs were generated, and PATCH version will be stub or plugin specific updates.

Custom Resource Definitions

Add type checks for Custom Resource Definition spec given its definition in yaml file .

1. Configure mypy to use crd_typed plugin:

[mypy]

plugins = crd_typed.plugin

2. Import CustomResource

from crd_type import CustomResource

3. Annotate your variables:

resource: CustomResource["relative/path/to/crd.yaml"]

You can get type definition for different parts of crd:

• Get TypeDict definition for custom resource body:

  from crd_type import CustomResource
  
  resource: CustomResource["relative/path/to/crd.yaml"]

• Get definition only for resource spec:

  from crd_type import CustomResource
  
  resource: CustomResource["relative/path/to/crd.yaml", "spec"]

• Get definition for nested spec item, if that item is type object or array:

  from crd_type import CustomResource
  
  resource: CustomResource["relative/path/to/crd.yaml", "spec", "some_property"]

• Get definition for array item, if that is array of objects, via items key:

  from crd_type import CustomResource
  
  resource: CustomResource["relative/path/to/crd.yaml", "spec", "some_array_of_objects", "items"]

Limitations

• CRDs that use additionalProperties are not supported.
• CRDs can define multiple versions, currently only first one will be used
• Custom attributes like x-kubernetes-int-or-string, x-kubernetes-embedded-resource, are not supported

Kubernetes Python Client types

This package provides basic type stubs for kubernetes python client out of the box.

To enable full type checking for classes use provided kubernetes_typed plugin. This plugin requires kubernetes, you can require it during installation like this:

pip install kubernetes-typed[client]

Configure mypy to use it and it will automatically type check classes from kubernetes.client:

[mypy]

plugins = kubernetes_typed.plugin

Kubernetes Python Client Models Dict Types

If you want to type check resource dicts instead of classes, you can use generated TypedDicts provided by this package.

To do this for any model class in kubernetes.client append its name with Dict, and import it from kubernetes_type.client

For example:

kubernetes.client.V1Pod -> kubernetes_typed.client.V1PodDict

from kubernetes.client.api import core_v1_api

from kubernetes_typed.client import V1PodDict

api_instance = core_v1_api.CoreV1Api()

pod_manifest: V1PodDict = {
    "apiVersion": "v1",
    "kind": "Pod",
    "metadata": {"name": "test-pod"},
    "spec": {
        "containers": [
            {
                "image": "nginx",
                "name": "nginx",
            },
        ],
    },
}

api_instance.create_namespaced_pod(body=pod_manifest, namespace='default')

Limitations

• Kubernetes client api functions are currently not covered by stubs, so you might get Call to untyped function errors. Check mypy config doc on how to disable separate warnings.