======================
Resources preloading
======================

Instead of defining resources one by one in tests,
the resource definitions can be loaded from prepared data files.
These files are generated from a real Kubernetes cluster
and contain the full API resource discovery information.

.. warning::

   The data format is opaque and should not be interpreted.
   Store and use the files exactly as generated by ``kmock fetch resources``.
   The format may change at any time without warning,
   but backward compatibility with files generated in older formats
   will always be maintained.


Loading resources
=================

There are three ways to load resource definitions
into the ``kmock.resources`` associative array.


From a file path
----------------

Use :meth:`~kmock.ResourcesArray.load_path`
to load resource definitions from a file on disk.
Gzip, bzip2, and zstd (Python 3.14+) compressed files are supported automatically
based on the file extension:

.. code-block:: python

    import kmock

    async def test_with_resource_file(kmock: kmock.KubernetesScaffold) -> None:
        kmock.resources.load_path('path/to/resources.dat')

        # Or compressed:
        kmock.resources.load_path('path/to/resources.gz')
        kmock.resources.load_path('path/to/resources.bz2')
        kmock.resources.load_path('path/to/resources.zst')  # Python 3.14+

Both string paths and :class:`pathlib.Path` objects are accepted.


From a data blob
----------------

Use :meth:`~kmock.ResourcesArray.load_data`
to load resource definitions from a string or bytes object,
for example when the resource file is bundled with your own package:

.. code-block:: python

    import gzip
    import importlib.resources

    import kmock

    async def test_with_raw_data(kmock: kmock.KubernetesScaffold) -> None:
        data = importlib.resources.read_binary('mypkg', 'resources.gz')
        kmock.resources.load_data(gzip.decompress(data))


From bundled data
-----------------

The simplest way is to use :meth:`~kmock.ResourcesArray.load_bundled`
to load the resource definitions bundled with the package.
This file is pre-built from a recent K3s cluster
and contains the standard Kubernetes builtins:

.. code-block:: python

    import kmock

    async def test_with_bundled_resources(kmock: kmock.KubernetesScaffold) -> None:
        kmock.resources.load_bundled()

        # Standard resources are now available for discovery:
        resp = await kmock.get('/api/v1')
        data = await resp.read()
        assert data['kind'] == 'APIResourceList'

The bundled data contains only the standard Kubernetes built-in resources
(core API, ``apps``, ``batch``, ``autoscaling``, ``policy``,
and the ``*.k8s.io`` groups).
It does not include any third-party CRDs or custom resources.
It might also be outdated or incomplete.
For anything beyond a quick "good enough" setup,
generate your own resource file (see below).

Multiple calls to any of the loading methods are additive:
the resources accumulate. If the same resource appears twice,
the last definition wins.


Generating resource files
=========================

The ``kmock fetch resources`` CLI command connects to a Kubernetes cluster
and dumps the API resource discovery information to a file.


Running the command
-------------------

The command uses the current kubeconfig context.
It relies on the ``kubernetes`` client library for API authentication,
which covers all the sophisticated authentication methods
(tokens, certificates, external auth providers, etc.).
Since the ``kubernetes`` library is too heavy
to include as a default runtime dependency,
it is available as an optional extra:

.. code-block:: shell

    pip install kmock[fetch]

Fetch resources and write to a file:

.. code-block:: shell

    kmock fetch resources -o resources.dat

The output format is determined by the file extension.
Use ``.gz``, ``.bz2``, or ``.zst`` (Python 3.14+) extensions for compressed output:

.. code-block:: shell

    kmock fetch resources -o resources.gz
    kmock fetch resources -o resources.bz2
    kmock fetch resources -o resources.zst

Omit ``-o`` to write to stdout:

.. code-block:: shell

    kmock fetch resources > resources.dat

Only the fields used by the loader are stored in the output file.
Unnecessary fields from the API responses (such as ``storageVersionHash``)
are stripped automatically.


Filtering groups
----------------

By default, only the standard Kubernetes groups are included:
the core API (``v1``), ``apps``, ``autoscaling``, ``batch``, ``policy``,
and all ``*.k8s.io`` groups.
Third-party CRDs and custom groups are excluded.

Use ``--include``/``-i`` to include additional groups or specific group/versions:

.. code-block:: shell

    # Include all versions of the kopf.dev group:
    kmock fetch resources -o resources.dat --include=kopf.dev

    # Include only a specific version:
    kmock fetch resources -o resources.dat --include=kopf.dev/v1

Use ``--exclude``/``-x`` to exclude groups or specific group/versions:

.. code-block:: shell

    # Exclude the metrics group:
    kmock fetch resources -o resources.dat --exclude=metrics.k8s.io

    # Exclude a specific version:
    kmock fetch resources -o resources.dat --exclude=autoscaling/v1

Use ``--include=*`` to include everything from the cluster:

.. code-block:: shell

    kmock fetch resources -o resources.dat --include=*

The filters support simple glob patterns
and are applied sequentially from left to right,
so they can be combined:

.. code-block:: shell

    # Include all kopf.dev versions except v2:
    kmock fetch resources -o resources.dat --include=kopf.dev --exclude=kopf.dev/v2

    # Include everything except third-party groups:
    kmock fetch resources -o resources.dat --include=* --exclude=helm.cattle.io --exclude=traefik.io