build_extension_module_result

scikitplot.cython.build_extension_module_result(*, code, source_path, module_name, cache_dir, use_cache, force_rebuild, verbose, profile=None, annotate, view_annotate, numpy_support, numpy_required, include_dirs, library_dirs, libraries, define_macros, extra_compile_args, extra_link_args, compiler_directives, extra_sources=None, support_files=None, support_paths=None, include_cwd=True, lock_timeout_s=60.0, language=None)

Compile and import an extension module, with deterministic caching.

Parameters:

codestr or None

Cython source string that is valid for a .pyx file. Exactly one of code or source_path must be provided.

source_pathpathlib.Path or None

Path to a .pyx file. Exactly one of code or source_path must be provided.

module_namestr or None

Optional explicit module name. If None, a deterministic name is derived from the cache key.

cache_dirstr or pathlib.Path or None

Root cache directory for build artifacts.

use_cachebool

If True, reuse a previously compiled artifact when the cache key matches.

force_rebuildbool

If True, rebuild even if a cached artifact exists.

verboseint

Build verbosity. Negative values suppress most build output.

profilestr or None

Optional profile label (e.g., “fast-debug”, “release”, “annotate”). This value is persisted in metadata for introspection but does not affect the cache key by itself (the actual build options do).

annotatebool

If True, generate a Cython annotation HTML file.

view_annotatebool

If True, open the annotation HTML file in a browser (requires annotate=True).

numpy_supportbool

If True, attempt to add NumPy include directories when NumPy is installed.

numpy_requiredbool

If True and numpy_support=True, raise ImportError when NumPy is not installed.

include_dirs, library_dirs, libraries, define_macros, extra_compile_args, extra_link_args

Standard extension build options passed to the C/C++ compiler and linker.

compiler_directivesMapping[str, Any] or None

Cython compiler directives (default includes language_level=3).

extra_sourcessequence of path-like, optional

Additional C/C++ sources to compile and link into the extension. Only files ending in [‘.c’, ‘.cc’, ‘.cpp’, ‘.cxx’] are accepted.

support_filesMapping[str, str | bytes] or None, optional

Extra support files written into the build directory when compiling from a source string (e.g., .pxi / .pxd / headers). Keys must be simple filenames (no directories). Values are written as UTF-8 text for str and as raw bytes for bytes.

support_pathssequence of path-like, optional

Extra support files copied into the build directory when compiling from a source file. Each file is copied by basename into the build directory.

include_cwdbool, default=True

If True, include the current working directory in include paths.

lock_timeout_sfloat, default=60.0

Maximum seconds to wait for the per-key build lock.

language{‘c’, ‘c++’} or None, default=None

Optional explicit language for the extension. If None, the build uses the default compiler behavior.

Returns:

scikitplot.cython.BuildResult

Structured build result including the imported module and metadata.

Raises:

ValueError

If inputs are invalid or unsupported.

ImportError

If required build dependencies are missing (Cython, setuptools, and optionally NumPy).

RuntimeError

If compilation fails.

Parameters:

• code (str | None)

• source_path (Path | None)

• module_name (str | None)

• cache_dir (str | Path | None)

• use_cache (bool)

• force_rebuild (bool)

• verbose (int)

• profile (str | None)

• annotate (bool)

• view_annotate (bool)

• numpy_support (bool)

• numpy_required (bool)

• include_dirs (Sequence[PathLike[str] | PathLike[bytes] | str | bytes] | None)

• library_dirs (Sequence[PathLike[str] | PathLike[bytes] | str | bytes] | None)

• libraries (Sequence[str] | None)

• define_macros (Sequence[tuple[str, str | None]] | None)

• extra_compile_args (Sequence[str] | None)

• extra_link_args (Sequence[str] | None)

• compiler_directives (Mapping[str, Any] | None)

• extra_sources (Sequence[PathLike[str] | PathLike[bytes] | str | bytes] | None)

• support_files (Mapping[str, str | bytes] | None)

• support_paths (Sequence[PathLike[str] | PathLike[bytes] | str | bytes] | None)

• include_cwd (bool)

• lock_timeout_s (float)

• language (str | None)

Return type:

BuildResult

Notes

The returned module is annotated with:

• __scikitplot_cython_key__: cache key

• __scikitplot_cython_build_dir__: build directory

• __scikitplot_cython_artifact__: compiled artifact path