scikitplot.cython#

scikitplot.cython#

A lightweight runtime Cython development kit with caching, pinning, garbage collection, and templating support.

scikitplot.cython enables real-time, in-place (in-situ) generation of low-level Cython packages and modules for immediate use and testing.

User guide. See the Runtime Cython compilation section for further details.

API Stability#

API_STABILITY

A dict that populates itself from the package __all__ on first use.

Stability

Stability tier of a public API symbol.

api_stability

Return the Stability tier of a public API symbol.

list_api

Return the sorted public symbol names in a given stability tier.

Build an Extension Module (PKG/MOD)#

DEFAULT_COMPILER_DIRECTIVES

build_extension_module

Compile and import an extension module (module-only convenience wrapper).

build_extension_module_result

Compile and import an extension module, with deterministic caching.

build_extension_package_from_code_result

Compile a package of multiple extension modules from in-memory code strings.

build_extension_package_from_paths_result

Compile a package of multiple extension modules from existing .pyx files.

Cache Management#

CACHE_SCHEMA_VERSION

int([x]) -> integer int(x, base=10) -> integer

CacheEntry

A compiled module cache entry.

PackageCacheEntry

A compiled package cache entry (multi-module build).

find_entries_by_name

Find module cache entries matching an exact module name.

find_entry_by_key

Find a single module cache entry by key.

find_package_entry_by_key

Find a single package cache entry by key.

is_meta_schema_compatible

Return whether meta can be trusted by the current reader.

is_valid_key

Return True if key is a valid cache key.

iter_all_entry_dirs

Return all cache entry directories whose name is a valid cache key.

iter_cache_entries

List module cache entries found under the cache directory.

iter_package_entries

List package cache entries found under the cache directory.

make_cache_key

Create a deterministic cache key from a JSON-serializable mapping.

meta_schema_version

Return the schema version recorded in meta (0 if absent/legacy).

peek_cache_dir

Resolve the cache directory path without creating it.

read_meta

Read meta.json from a build directory.

register_artifact_path

Register an existing compiled extension artifact into the cache registry.

resolve_cache_dir

Resolve and create the cache directory.

runtime_fingerprint

Compute a runtime fingerprint for caching correctness.

source_digest

SHA-256 digest of source bytes.

write_meta

Write meta.json in the build directory atomically.

Custom Compiler Protocol#

CustomCompilerProtocol

Structural protocol for custom compiler callables.

CompilerRegistry

Thread-safe module-level registry of custom compiler callables.

register_compiler

Register a custom compiler in the module-level registry.

get_compiler

Retrieve a registered custom compiler by name.

list_compilers

Return sorted list of registered custom compiler names.

CompilerCapabilities

Versioned, declarative description of a custom compiler's capabilities.

compiler_capabilities

Return the CompilerCapabilities a compiler declares.

COMPILER_SPEC_VERSION

int([x]) -> integer int(x, base=10) -> integer

pure_python_prereqs

Check prerequisites pure Python, setuptools only.

cython_cpp_prereqs

Check prerequisites compile C++ via Cython.

full_stack_prereqs

Check prerequisites full stack setuptools, Cython, pybind11, and NumPy.

pybind11_only_prereqs

Check prerequisites pybind11 only.

c_api_prereqs

Check prerequisites own custom C-API.

pybind11_include

Return the pybind11 include directory, or None if not installed.

numpy_include

Return the NumPy C-API include directory, or None if not installed.

collect_c_api_sources

Collect C/C++ source files from one or more files, directories, or globs.

collect_header_dirs

Collect unique directories that contain C/C++ header files.

PybindCompiler

Built-in custom compiler: pybind11-only projects.

CApiCompiler

Built-in custom compiler: NumPy C-API projects.

Cache Management Utilities#

cache_stats

Compute cache statistics.

gc_cache

Deterministically garbage-collect cached build entries.

Loader Extension Module#

import_extension

Import an extension module from an explicit artifact path.

import_extension_from_bytes

Import an extension module from raw artifact bytes.

import_extension_from_path

Import an extension module from a filesystem path.

Locker Cross-platform Build#

build_lock

Acquire an exclusive build lock via atomic directory creation.

Pins/Aliases Registry#

PinRegistryError

Raised when the pin registry (pins.json) is corrupt or unreadable.

list_pins

List the current alias→key mappings.

pin

Pin a cache key under a human-friendly alias.

resolve_pinned_key

Resolve an alias to a cache key.

unpin

Remove an alias pin.

Profile Preset Builder#

AppliedProfile

Result of applying a profile with user-precedence rules.

PlatformCapabilities

Declarative contract describing what the current platform supports.

ProfileDefaults

Normalized defaults produced by resolving a profile.

ResolvedToolchain

The compiler the build backend actually selects (CYTHON-PORT-001).

RuntimeCapabilities

Declared contract for native-extension runtime lifecycle (CYTHON-ABI-001).

UnsupportedRuntimeError

Raised when a runtime lifecycle operation is not supported (CYTHON-ABI-001).

apply_profile

Apply a profile with strict, three-state precedence.

check_runtime_supported

Fail fast on an unsupported runtime configuration (CYTHON-ABI-001).

is_windows

Return True if the host operating system is native Windows.

platform_capabilities

Return the PlatformCapabilities contract for this process.

resolve_profile

Resolve a profile name to deterministic defaults.

resolved_toolchain

Return the compiler the build backend actually selects (CYTHON-PORT-001).

runtime_capabilities

Return the RuntimeCapabilities contract for this process.

Public API#

build_package_from_code

Build and import a multi-module extension package and return loaded modules.

build_package_from_code_result

Build and import a multi-module extension package from code strings.

build_package_from_paths

Build and import a multi-module extension package and return loaded modules.

build_package_from_paths_result

Build and import a multi-module extension package from .pyx file paths.

check_build_prereqs

Check whether build prerequisites are importable.

compile_and_load

Compile and import a Cython extension module and return the loaded module.

compile_and_load_result

Compile and import a Cython extension module from source text.

cython_import

Compile/import a Cython module from a .pyx file and return the loaded module.

cython_import_all

Compile and import all .pyx files in a directory.

cython_import_all_result

Compile and import all .pyx files in a directory, with a partial report.

cython_import_result

Compile/import a Cython module from a .pyx file.

export_cached

Export a cache entry directory to a destination folder.

get_cache_dir

Resolve (and create) the cache root directory.

import_artifact_bytes

Import a compiled extension artifact from raw bytes.

import_artifact_path

Import a compiled extension artifact from a path.

import_cached

Import a cached module entry and return the loaded module.

import_cached_by_name

Import the newest cached module entry matching module_name.

import_cached_package

Import a cached package and return the loaded modules.

import_cached_package_result

Import a cached package entry by cache key.

import_cached_result

Import a cached module entry by cache key.

import_pinned

Import a pinned alias and return the loaded module(s).

import_pinned_result

Import a pinned alias.

list_cached

List cached module entries.

list_cached_packages

List cached package entries.

purge_cache

Delete the entire cache directory.

register_cached_artifact_bytes

Register a compiled extension artifact from bytes and import it.

register_cached_artifact_path

Register an existing compiled extension artifact on disk, then import it.

Result Types#

BatchBuildError

Raised by fail-fast batch builds, carrying the partial result.

BatchBuildResult

Structured result of a batch compile/import (CYTHON-BATCH-001).

BatchFailure

A single failure within a batch build (CYTHON-BATCH-001).

BuildResult

Result of compiling/importing a single Cython extension module.

CacheGCResult

Result of a cache garbage-collection operation.

CacheStats

Cache statistics for the compiled-artifact cache root.

PackageBuildResult

Result of compiling/importing a package of extension modules.

Security Guards#

DEFAULT_SECURITY_POLICY

Immutable security policy applied to build inputs before compilation.

RELAXED_SECURITY_POLICY

Immutable security policy applied to build inputs before compilation.

SecurityError

Raised when a build input violates the active SecurityPolicy.

SecurityPolicy

Immutable security policy applied to build inputs before compilation.

is_safe_compiler_arg

Return True when a compiler argument string is safe to pass.

is_safe_macro_name

Return True when a C preprocessor macro name is safe to define.

is_safe_path

Return True when a filesystem path does not contain traversal sequences.

validate_build_inputs

Validate build inputs against a SecurityPolicy.

Template and Workflow Assets#

TEMPLATE_SCHEMA_VERSION

int([x]) -> integer int(x, base=10) -> integer

TemplateInfo

Structured metadata for a template.

TemplateValidationError

Raised when template metadata fails strict schema validation.

build_package_example

Build and import a multi-module package example and return loaded modules.

build_package_example_result

Build and import a multi-module package example and return a structured result.

compile_template

Compile and import a Cython template and return the loaded module.

compile_template_result

Compile and import a Cython template and return a structured result.

copy_workflow

Copy a workflow template folder to a destination directory.

generate_sphinx_template_docs

Generate Sphinx .rst pages listing templates and their usage.

get_package_example_path

Resolve a package example name to its on-disk folder path.

get_template_path

Resolve a template ID to an on-disk path.

get_workflow_path

Resolve a workflow name to its on-disk folder path.

list_package_examples

List available multi-module package examples.

list_templates

List available templates.

list_workflows

List available workflow template folders.

load_package_example_metadata

Load package example metadata from package.meta.json.

load_template_metadata

Load template metadata from an adjacent *.meta.json file.

read_template

Read template source text.

read_template_info

Read metadata for a template and return a TemplateInfo.

template_root

Return the on-disk template root directory.

validate_template_info

Strictly validate template metadata against the schema (CYTHON-TPL-002).

verify_template_assets

Verify every referenced template support asset is actually shipped.

workflow_cli_template_path

Return the workflow CLI template path.

Small utilities#

sanitize

Convert an arbitrary string into a valid, collision-resistant module name.