Cache and restart reuse#

Compiled artifacts are cached on disk. After a Python kernel restart, you can import the cached module again without recompiling (as long as the runtime fingerprint matches).

This example demonstrates:

compiling a snippet
listing cached entries
importing the same module from the cache by key
(optional) showing cache stats

# Authors: The scikit-plots developers
# SPDX-License-Identifier: BSD-3-Clause

from __future__ import annotations

from typing import Any

from scikitplot import cython

def _print_entry_summary(entries: list[Any], limit: int = 5) -> None:
    """Print a stable cache listing summary."""
    print("Cache entries:", len(entries))
    if not entries:
        return

    # Print last few entries by whatever order list_cached returns.
    tail = entries[-limit:]
    print(f"Last {len(tail)} entries:")
    for e in tail:
        # CacheEntry is expected to have these (defaults exist).
        print("  - key:", getattr(e, "key", None))
        print("    module_name:", getattr(e, "module_name", None))
        print("    artifact_path:", getattr(e, "artifact_path", None))
        print("    created_utc:", getattr(e, "created_utc", None))

Generate `python` Module from `python`#

report = cython.check_build_prereqs(numpy=False)

if not report.get('cython', {}).get('ok'):
    print("Skipping compilation because build prerequisites are missing.")
    problems = report.get("problems", [])
    if problems:
        print("Problems:", problems)
else:
    # 1) Compile a snippet and capture its deterministic cache key.
    r = cython.compile_and_load_result("def f(int n):\n    return n*n\n", profile="fast-debug", verbose=0)
    key = r.key

    print("\nBuildResult:")
    print("  module_name:", r.module_name)
    print("  key        :", r.key)
    print("  artifact   :", r.artifact_path)
    print("  used_cache :", r.used_cache)

    # 2) List cache entries (safe if empty).
    entries = cython.list_cached()
    _print_entry_summary(entries)

    # Optional: cache stats snapshot (if available).
    if hasattr(cython, "cache_stats"):
        print("\nCache stats snapshot:")
        print(cython.cache_stats())

    # 3) Import the same module by key (restart-safe mechanism).
    # Use import_cached_result if available so we can inspect metadata.
    if hasattr(cython, "import_cached_result"):
        r2 = cython.import_cached_result(key)
        m2 = r2.module
        print("\nImported from cache (result API):")
        print("  module_name:", r2.module_name)
        print("  used_cache :", r2.used_cache)
        print("  artifact   :", r2.artifact_path)
    else:
        m2 = cython.import_cached(key)
        print("\nImported from cache (module API):", m2.__name__)

    # 4) Verify correctness strictly.
    out = m2.f(11)
    print("import_cached(key).f(11) =", out)
    print("Expected:", 121)
    print("Correct:", out == 121)

BuildResult:
  module_name: scikitplot_cython_b82a7d5a410e110f
  key        : b82a7d5a410e110f658412dad516f578eab39189361958efd923b876759fc411
  artifact   : /home/circleci/.cache/scikitplot/cython/b82a7d5a410e110f658412dad516f578eab39189361958efd923b876759fc411/scikitplot_cython_b82a7d5a410e110f.cpython-311-x86_64-linux-gnu.so
  used_cache : True
Cache entries: 5
Last 5 entries:
  - key: 27e834d4d9b9704b6531d579adba3e067590eb11fa92da0e71dbff68fab3b664
    module_name: scikitplot_cython_27e834d4d9b9704b
    artifact_path: /home/circleci/.cache/scikitplot/cython/27e834d4d9b9704b6531d579adba3e067590eb11fa92da0e71dbff68fab3b664/scikitplot_cython_27e834d4d9b9704b.cpython-311-x86_64-linux-gnu.so
    created_utc: 2026-04-12T09:11:59Z
  - key: 30e033b9a404ca4d13e5e35fc0fe0e7882e6e681c3f3031e37440422f028cdc1
    module_name: scikitplot_cython_30e033b9a404ca4d
    artifact_path: /home/circleci/.cache/scikitplot/cython/30e033b9a404ca4d13e5e35fc0fe0e7882e6e681c3f3031e37440422f028cdc1/scikitplot_cython_30e033b9a404ca4d.cpython-311-x86_64-linux-gnu.so
    created_utc: 2026-04-12T09:12:02Z
  - key: b82a7d5a410e110f658412dad516f578eab39189361958efd923b876759fc411
    module_name: scikitplot_cython_b82a7d5a410e110f
    artifact_path: /home/circleci/.cache/scikitplot/cython/b82a7d5a410e110f658412dad516f578eab39189361958efd923b876759fc411/scikitplot_cython_b82a7d5a410e110f.cpython-311-x86_64-linux-gnu.so
    created_utc: 2026-04-12T09:11:59Z
  - key: c7f8ca5a32702f90198772919c7ee4ee9469d54dcd587e81217b6f20942038a3
    module_name: scikitplot_cython_c7f8ca5a32702f90
    artifact_path: /home/circleci/.cache/scikitplot/cython/c7f8ca5a32702f90198772919c7ee4ee9469d54dcd587e81217b6f20942038a3/scikitplot_cython_c7f8ca5a32702f90.cpython-311-x86_64-linux-gnu.so
    created_utc: 2026-04-12T09:12:00Z
  - key: f52b9ea7da4c44ddfa2fe6ff8fac643a390d2f1726a87b92dcd908ec9ac22c77
    module_name: scikitplot_cython_f52b9ea7da4c44dd
    artifact_path: /home/circleci/.cache/scikitplot/cython/f52b9ea7da4c44ddfa2fe6ff8fac643a390d2f1726a87b92dcd908ec9ac22c77/scikitplot_cython_f52b9ea7da4c44dd.cpython-311-x86_64-linux-gnu.so
    created_utc: 2026-04-12T09:12:02Z

Cache stats snapshot:
CacheStats(cache_root=PosixPath('/home/circleci/.cache/scikitplot/cython'), n_modules=5, n_packages=0, total_bytes=3450291, pinned_aliases=1, pinned_keys=1, newest_mtime_utc='2026-04-12T09:12:03Z', oldest_mtime_utc='2026-04-12T09:11:59Z')

Imported from cache (result API):
  module_name: scikitplot_cython_b82a7d5a410e110f
  used_cache : True
  artifact   : /home/circleci/.cache/scikitplot/cython/b82a7d5a410e110f658412dad516f578eab39189361958efd923b876759fc411/scikitplot_cython_b82a7d5a410e110f.cpython-311-x86_64-linux-gnu.so
import_cached(key).f(11) = 121
Expected: 121
Correct: True

Tags: domain: cython plot-type: cython purpose: showcase

Total running time of the script: (0 minutes 0.010 seconds)

Related examples