.. DO NOT EDIT. .. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY. .. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE: .. "auto_examples/cython/plot_01_browse_and_compile_templates.py" .. LINE NUMBERS ARE GIVEN BELOW. .. only:: html .. note:: :class: sphx-glr-download-link-note :ref:`Go to the end ` to download the full example code or to run this example in your browser via JupyterLite or Binder. .. rst-class:: sphx-glr-example-title .. _sphx_glr_auto_examples_cython_plot_01_browse_and_compile_templates.py: Browse and compile templates ============================ .. currentmodule:: scikitplot.cython This example shows how to: - list available templates - read a template source file - compile a selected template - inspect the compiled module - handle missing templates or build prerequisites gracefully (docs-safe) Notes ----- Templates are shipped as package data under ``_templates/``. If your packaging configuration excludes them, this example will print a clear message and exit. Compilation requires build prerequisites; we check them first to keep gallery builds stable. .. GENERATED FROM PYTHON SOURCE LINES 23-27 .. code-block:: Python # Authors: The scikit-plots developers # SPDX-License-Identifier: BSD-3-Clause .. GENERATED FROM PYTHON SOURCE LINES 28-35 .. code-block:: Python from __future__ import annotations from typing import Any, Iterable from scikitplot import cython .. GENERATED FROM PYTHON SOURCE LINES 36-83 .. code-block:: Python def _preview_text(s: str, n: int = 250) -> str: s2 = s.replace("\r\n", "\n") if len(s2) <= n: return s2 return s2[:n] + "\n..." def _safe_call_from_metadata(module: Any, demo_calls: Iterable[dict[str, Any]]) -> bool: """ Execute strictly declared demo calls. The metadata schema is expected to include demo calls like: {"func": "square", "args": [12]} This function executes only declared calls, with no guessing. """ any_called = False for call in demo_calls: func_name = call.get("func") args = call.get("args", []) kwargs = call.get("kwargs", {}) if not isinstance(func_name, str): continue f = getattr(module, func_name, None) if not callable(f): continue try: out = f(*args, **kwargs) except Exception as e: print(f"Demo call failed: {module.__name__}.{func_name}{tuple(args)!r} -> {type(e).__name__}: {e}") else: print(f"Demo call: {module.__name__}.{func_name}(*{args!r}, **{kwargs!r}) -> {out!r}") any_called = True return any_called def _public_names(module: Any, limit: int = 20) -> list[str]: names = sorted( n for n in getattr(module, "__dict__", {}).keys() if n and not n.startswith("_") ) return names[:limit] .. GENERATED FROM PYTHON SOURCE LINES 84-87 List all available module tamplates ----------------------------------- https://scikit-plots.github.io/dev/user_guide/cython/_templates/templates_index.html .. GENERATED FROM PYTHON SOURCE LINES 87-92 .. code-block:: Python templates = cython.list_templates() print("Template count:", len(templates)) print("First 8:", templates[:8]) .. rst-class:: sphx-glr-script-out .. code-block:: none Template count: 75 First 8: ['basic_cython/t01_square_int', 'basic_cython/t02_add_float', 'basic_cython/t03_toggle_bool', 'basic_cython/t04_repeat_str', 'basic_cython/t05_int_overflow_demo', 'basic_cython/t06_xor_bytes', 'complex_cython/t01_cpp_vector_sum', 'complex_cython/t01_fast_clip'] .. GENERATED FROM PYTHON SOURCE LINES 93-95 Generate `python` Module from `cython` -------------------------------------- .. GENERATED FROM PYTHON SOURCE LINES 95-152 .. code-block:: Python # Pick a template deterministically and safely. if not templates: print( "No templates found.\n" "This usually means templates were not included as package data.\n" "Ensure your packaging includes scikitplot/cython/_templates/**." ) else: name = templates[0] path = cython.get_template_path(name) print("\nTemplate:", name) print("Path:", path) src = cython.read_template(name) print("\nSource preview:\n") print(_preview_text(src, 250)) # Check build prerequisites (docs-safe). report = cython.check_build_prereqs(numpy=False) if not report.get('cython', {}).get('ok'): print("\nSkipping compilation because build prerequisites are missing.") problems = report.get("problems", []) if problems: print("Problems:", problems) else: # Compile the selected template. # # Prefer compile_template_result so we can display metadata. r = cython.compile_template_result(name, profile="fast-debug", verbose=0) print("\nBuildResult:") print(" module_name:", r.module_name) print(" key :", r.key) print(" artifact :", r.artifact_path) print(" used_cache :", r.used_cache) mod = r.module print("\nImported module:", mod.__name__) print("Public names:", _public_names(mod)) # Strict demo execution: # 1) If template metadata declares demo calls, use them. # 2) Otherwise do NOT guess signatures; just print public names. info = getattr(cython, "read_template_info", None) if callable(info): meta = info(name) demo_calls = getattr(meta, "demo_calls", None) if demo_calls: print("\nRunning metadata-declared demo calls:") called = _safe_call_from_metadata(mod, demo_calls) if not called: print("No declared calls could be executed.") else: print("\nNo demo_calls declared in template metadata; skipping execution.") else: print("\nTemplate metadata reader not available; skipping execution.") .. rst-class:: sphx-glr-script-out .. code-block:: none Template: basic_cython/t01_square_int Path: /home/circleci/.pyenv/versions/3.11.14/lib/python3.11/site-packages/scikitplot/cython/_templates/basic_cython/t01_square_int.pyx Source preview: # cython: language_level=3 """Basic Cython template: typed function. This demonstrates a minimal compiled function with C integer typing. """ def square(int n): """Return n*n using C integer arithmetic.""" return n * n BuildResult: module_name: scikitplot_cython_632e06e9a1a7a877 key : 632e06e9a1a7a87769ae8f9e448b50fa2865f5211a9c7fac72db477b95832e8d artifact : /home/circleci/.cache/scikitplot/cython/632e06e9a1a7a87769ae8f9e448b50fa2865f5211a9c7fac72db477b95832e8d/scikitplot_cython_632e06e9a1a7a877.cpython-311-x86_64-linux-gnu.so used_cache : False Imported module: scikitplot_cython_632e06e9a1a7a877 Public names: ['square'] No demo_calls declared in template metadata; skipping execution. .. GENERATED FROM PYTHON SOURCE LINES 153-158 .. tags:: domain: cython plot-type: cython purpose: showcase .. rst-class:: sphx-glr-timing **Total running time of the script:** (0 minutes 1.167 seconds) .. _sphx_glr_download_auto_examples_cython_plot_01_browse_and_compile_templates.py: .. only:: html .. container:: sphx-glr-footer sphx-glr-footer-example .. container:: binder-badge .. image:: images/binder_badge_logo.svg :target: https://mybinder.org/v2/gh/scikit-plots/scikit-plots/main?urlpath=lab/tree/notebooks/auto_examples/cython/plot_01_browse_and_compile_templates.ipynb :alt: Launch binder :width: 150 px .. container:: lite-badge .. image:: images/jupyterlite_badge_logo.svg :target: ../../lite/lab/index.html?path=auto_examples/cython/plot_01_browse_and_compile_templates.ipynb :alt: Launch JupyterLite :width: 150 px .. container:: sphx-glr-download sphx-glr-download-jupyter :download:`Download Jupyter notebook: plot_01_browse_and_compile_templates.ipynb ` .. container:: sphx-glr-download sphx-glr-download-python :download:`Download Python source code: plot_01_browse_and_compile_templates.py ` .. container:: sphx-glr-download sphx-glr-download-zip :download:`Download zipped: plot_01_browse_and_compile_templates.zip ` .. include:: plot_01_browse_and_compile_templates.recommendations .. only:: html .. rst-class:: sphx-glr-signature `Gallery generated by Sphinx-Gallery `_