Python API

The 2.0 API is project-oriented. The v1 Target API remains supported throughout 2.x for phase-local checks and migration.

Primary project workflow

import researchplot as rp

project = rp.Project.load("researchplot.toml")
plan = project.plan(frozen=True)
report = plan.check()

if report.verdict is rp.Verdict.COMPLIANT:
    bundle = project.bundle("dist/submission")

frozen=True requires ProjectSpec.lock_path and verifies the exact profile before checking artifacts.

Figure workflow

figure = project.figure("figure-1")

with figure.style(deliverable="main", latex=False) as style:
    fig, ax = style.subplots(aspect=0.62)
    ax.plot(x, y)
    report = figure.check(fig=fig)
    export = figure.export(fig, policy="violations")

figure.check() combines configured bundle metadata, existing deliverables, and an optional live Matplotlib figure. Use figure.validate(fig) or figure.audit(path) only when a raw phase-local compatibility Report is intentional.

Project specifications

Immutable ResearchPlot 2 project and deliverable specifications.

The specification layer is deliberately independent from Matplotlib and artifact parsers. It describes intent; :mod:researchplot.project_api resolves that intent against an installed venue profile and turns it into a compliance plan.

ProjectSpec dataclass

Strict schema-v3 project intent, independent of an installed profile object.

figure(figure_id)

Return one figure by id or raise an actionable error.

load(path='researchplot.toml') classmethod

Load and strictly validate a schema-v3 TOML project.

FigureSpec dataclass

A logical figure and all representations intended for submission.

attestation_statements property

Compatibility projection consumed by the manual-rule engine.

active_waiver_rule_ids property

Return non-expired waiver IDs without changing compliance semantics.

PanelSpec dataclass

Metadata and evidence paths for one panel in a logical figure.

DeliverableSpec dataclass

One concrete representation of a logical research figure.

ManuscriptSpec dataclass

An optional compiled manuscript plus conservative figure matching hints.

ManuscriptMatchHint dataclass

Conservative hints for locating a figure in a compiled manuscript.

ManuscriptFormat

Bases: StrEnum

Manuscript containers represented by a project specification.

ManualAttestation dataclass

Reviewer-authored evidence for a profile rule classified as manual.

Waiver dataclass

Reviewable workflow exception that never changes the venue verdict.

project_schema()

Return an independent copy of the bundled schema-v3 project contract.

Planning and coverage

Export planning and coverage-aware project compliance semantics.

CompliancePlan dataclass

Resolved project targets plus explicit required-evidence coverage.

assess(evidence)

Derive a tri-state verdict without treating absent phases as success.

FigurePlan dataclass

ExportPlan dataclass

A no-write explanation of formats and settings selected for a target.

ExportSetting dataclass

Resolved artifact settings for one selected output format.

CoverageRequirement dataclass

One required rule/phase that a project plan expects evidence for.

CoverageResult dataclass

CoverageStatus

Bases: StrEnum

Whether required evidence was present and conclusive.

PlanEvidence dataclass

A report associated with one logical figure and optional deliverable.

PlanAssessment dataclass

Coverage-aware project verdict and all evidence used to derive it.

warnings property

Recommendation failures that do not determine the venue verdict.

sources property

Unique official sources carried by all phase reports.

remediations property

Unique deterministic suggestions attached to evaluated findings.

blocks(policy=Policy.COMPLETE)

Return whether a v1-compatible policy blocks this aggregate verdict.

plan_export(target, *, formats=None, preferred=None)

Resolve an explicit, no-write export plan for a v1 or v2 target.

Unlike the legacy implicit exporter, an omitted formats selects one preferred representation plus any explicitly encoded required companions. This behavior is exposed through the planner only; :meth:Target.export retains its 1.x behavior.

Project execution

ResearchPlot 2 project orchestration built on immutable specifications.

Project dataclass

Resolved schema-v3 project with planning and coverage-aware checks.

load(path='researchplot.toml') classmethod

Load a strict schema-v3 TOML project and resolve its pinned profile.

plan(*, frozen=False)

Return the executable compliance plan used by the primary v2 workflow.

frozen=True verifies the configured profile lock immediately and again before checking any artifacts.

figure(figure_id)

Return a figure-scoped style/check/export facade.

target(figure_id)

Return the resolved target used by one figure plan.

assess(*evidence)

Assess caller-supplied live, file, or bundle evidence against the plan.

audit_manuscript(*, max_pages=2000)

Audit the configured compiled PDF and conservatively match figure placements.

Placement matching is coverage evidence, not an acceptance guarantee. Missing or ambiguous placements remain unresolved and are never inferred as passing.

check(*, live_figures=None)

Audit configured artifacts and bundle metadata without hiding live-only gaps.

bundle(output_dir, *, live_figures=None)

Build a v1-compatible staged bundle from this immutable project.

A live figure can produce every planned representation. Existing-file projects must currently select one preferred representation per logical figure; generic attachments and multi-file source-data sets require a future bundle manifest.

ExecutablePlan dataclass

Thin executable facade over an immutable :class:CompliancePlan.

verify_lock()

Verify exact profile and evidence digests without inspecting artifacts.

FigureTarget dataclass

Figure-scoped style, check, audit, and export conveniences.

style(*, deliverable=None, latex=False, overrides=None)

Create the reversible Matplotlib context resolved for this figure.

validate(fig)

Return the raw live-phase report for callers that do not need coverage.

audit(path)

Return the raw file-phase report for an existing representation.

check(*, fig=None, include_artifacts=True)

Assess this figure without unrelated project figures becoming coverage gaps.

export(fig, target_path=None, *, formats=None, policy=None, dpi=None, overwrite=False, metadata=None, **savefig_kwargs)

Export through the resolved plan, defaulting to declared artifact paths.

PlanPolicyError

Bases: ValueError

Raised when a coverage-aware project assessment is blocked by policy.

enforce_assessment(assessment, policy=Policy.COMPLETE)

Return an assessment or raise when the selected policy blocks it.

Profiles and locks

profile = rp.resolve_profile("nature@2026.08.0")
profiles = rp.list_profiles()
matches = rp.search_profiles("vision")
lock = rp.ProfileLock.from_profile(profile)
report_v2_schema = rp.validation_report_schema()

Public immutable models used by ResearchPlot.

The profile models deliberately contain no Matplotlib objects. They can be loaded, inspected, hashed, and serialised in a completely offline process.

ProfileCoordinate dataclass

Canonical, optionally content-pinned profile coordinate.

The built-in namespace is omitted when rendered so existing coordinates such as nature@2026.08.0 remain valid. Third-party registries render an explicit namespace, for example lab.example/nature@2026.08.0.

VenueProfile dataclass

Immutable, validated venue specification.

coordinate property

Immutable profile coordinate, for example nature@2026.08.0.

pinned_coordinate property

Coordinate pinned to the resolved profile content digest.

profile_revision property

Explicit alias used by profile-lock and manifest consumers.

width_options property

Available figure width names for this profile.

get_rule(rule_id)

Return a rule by identifier, or None when unspecified.

rules_with_prefix(prefix)

Return all rules whose identifiers start with prefix.

width_mm(width=None)

Return an allowed figure width in millimetres.

VenueRule dataclass

A single source-backed rule in a venue profile.

value property

Compatibility view of :attr:constraint for the 0.2 API.

unit property

Compatibility view of :attr:constraint for the 0.2 API.

applicability property

Readable alias for the JSON field name :attr:applies_to.

SourceRef dataclass

An official source used to establish venue rules.

ProfileGovernance dataclass

Review metadata carried by schema-v3 profiles.

ProfileStatus

Bases: StrEnum

Governance state of a profile document.

RuleApplicability dataclass

Conditions under which a rule is relevant.

An empty tuple means "all values" for that dimension. This makes the common, venue-wide rule compact while keeping applicability explicit for role-, content-, and format-specific requirements.

formats property

Short compatibility alias for :attr:output_formats.

matches(*, role=None, content_kind=None, output_format=None, width=None)

Return whether supplied target metadata satisfies this filter.

RuleConstraint dataclass

The comparison encoded by a venue rule.

ProbeExpression dataclass

A typed comparison against one observation probe.

AllExpression dataclass

An expression that succeeds only when every child succeeds.

AnyExpression dataclass

An expression that succeeds when at least one child succeeds.

NotExpression dataclass

Logical negation of another rule expression.

QuantifierExpression dataclass

Apply one constraint to every or any member of a bounded observation.

AggregateExpression dataclass

Compare a count, minimum, or maximum derived from an observation.

ConstraintOperator

Bases: StrEnum

A stable, machine-readable comparison operator.

RuleLevel

Bases: StrEnum

How authoritative a venue rule is.

RulePhase

Bases: StrEnum

The validation stage in which a rule can be evaluated.

VerificationMode

Bases: StrEnum

How ResearchPlot can establish whether a rule is satisfied.

VenueKind

Bases: StrEnum

The publication venue category.

FigureRole

Bases: StrEnum

Where a figure will appear in a submission.

ContentKind

Bases: StrEnum

The visual content represented by an artifact.

This is intentionally separate from :class:OutputFormat: a line-art figure may be exported as either PDF or TIFF, for example.

OutputFormat

Bases: StrEnum

File formats understood by bundled profile applicability rules.

Deterministic profile locks and enforcement.

ProfileLock dataclass

ProfileLockError

Bases: ValueError

A profile lock is malformed, stale, or content-mismatched.

load_profile_lock(path='researchplot.lock.json')

Load a bounded, strictly-shaped lock file.

verify_profile_lock(lock, profile)

Raise when any locked identity or evidence digest has drifted.

resolve_locked_profile(lock)

Resolve the exact coordinate and enforce every lock digest.

Artifact inspection and remediation

execution = rp.inspect_artifact_isolated("figure.pdf")
inspection = execution.inspection
remediation = rp.plan_remediation(inspection)

Bounded artifact inspection and reproducible evidence-archive verification.

This module deliberately keeps parser isolation and archive integrity separate from venue policy. It never executes embedded content and never extracts an archive to disk while verifying it.

InspectionBudget dataclass

Per-artifact limits for an isolated inspection process.

BatchInspectionBudget dataclass

Aggregate limits for inspecting an artifact collection.

InspectionExecution dataclass

Result and accounting metadata from an isolated parser process.

ManifestIssue dataclass

One stable integrity or portability issue.

ManifestVerification dataclass

Integrity result for a directory or archive manifest.

ArchiveResult dataclass

A reproducibly encoded ZIP and its integrity result.

inspect_artifact_isolated(path, *, budget=None)

Inspect one artifact in a disposable child process.

On POSIX, address-space and CPU rlimits are applied when the host permits them. Every platform receives a process boundary, a parent-enforced file size check, and a wall-clock timeout. This is containment, not a claim of an operating-system filesystem sandbox.

inspect_artifacts_bounded(paths, *, budget=None)

Inspect a deterministic, duplicate-free artifact collection within a budget.

verify_manifest(root, *, manifest_name=_MANIFEST_NAME, strict=False)

Verify every declared file in a bundle directory without following symlinks.

create_deterministic_archive(source_dir, destination, *, manifest_name=_MANIFEST_NAME, strict=True)

Encode a verified manifest bundle as a byte-reproducible ZIP or TAR archive.

verify_deterministic_archive(path, *, manifest_name=_MANIFEST_NAME, require_deterministic_metadata=True)

Verify a ResearchPlot ZIP or TAR in place without extracting any member.

Deterministic, non-mutating remediation guidance for inspected artifacts.

Remediation dataclass

One traceable human action; ResearchPlot never applies it implicitly.

RemediationPlan dataclass

Ordered remediation guidance derived only from measured facts.

RemediationKind

Bases: StrEnum

Stable category for a corrective action.

plan_remediation(inspection)

Classify passive inspector observations into deterministic human guidance.

Visual and manuscript diagnostics

Deterministic accessibility previews and lightweight visual diagnostics.

AccessibilityPreview dataclass

All deterministic previews generated from one rendered figure.

PreviewImage dataclass

One in-memory PNG accessibility preview.

VisualDiagnostic dataclass

One measured visual signal and its interpretation.

VisualDiagnostics dataclass

Visual measurements plus the accessibility preview set.

render_accessibility_previews(source, *, dpi=144.0)

Render original, grayscale, and three colour-vision screening previews.

diagnose_visual(source, *, dpi=144.0)

Measure broad contrast, clipping, alpha, and entropy signals.

These signals are review prompts rather than pass/fail venue rules. They intentionally avoid OCR and semantic claims about labels or meaning.

write_accessibility_previews(preview, directory, *, stem='figure')

Write previews exclusively so existing review evidence is never replaced.

Passive, page-level audit of manuscript PDFs.

The manuscript auditor measures layout and embedded figure-resource facts. It does not render, execute actions, fetch links, or claim that a manuscript meets a publisher's full submission policy.

ManuscriptAudit dataclass

Immutable manuscript-wide audit result.

ManuscriptPageAudit dataclass

Measured resources and visible size for one manuscript page.

audit_manuscript_pdf(path, *, max_pages=_MAX_MANUSCRIPT_PAGES, figures=None, matching_hints=())

Audit passive PDF structure and, when configured, conservative placements.

The structural result optionally carries a conservative placement audit when configured figures are supplied.

Conservative figure-placement matching for compiled manuscript PDFs.

The matcher is intentionally passive and evidence ordered. It reads PDF object and content streams but never executes actions, follows links, performs OCR, or contacts a service. A result is resolved only when the strongest available evidence identifies exactly one measurable placed object.

ManuscriptPlacementAudit dataclass

Coverage report for all configured figure placements in one manuscript.

FigurePlacementMatch dataclass

Placement evidence and resolution state for one logical figure.

PlacedObject dataclass

One image or Form XObject invocation measured in page user space.

PlacementMatchMethod

Bases: StrEnum

Evidence that associated a configured figure with a placed object.

PlacementMatchStatus

Bases: StrEnum

Resolution state for one configured figure.

match_manuscript_figures(path, figures, *, hints=(), max_pages=_MAX_PAGES)

Match configured figures to unique measurable placements in a compiled PDF.

Evidence priority is embedded ResearchPlot provenance, exact decoded raster fingerprints, then author-configured page/number/caption hints. Ambiguous evidence is never replaced by weaker evidence.

Placement matching is conservative; a complete placement set is not yet integrated with venue-specific manuscript rules in CompliancePlan.

Allowlisted external inspectors

The optional extension boundary is a versioned, JSON-only subprocess protocol. Exact executables and support files must be explicitly allowlisted; capability negotiation, hash pins, timeouts, output limits, and typed observations fail closed.

Secure process boundary for explicitly trusted third-party inspectors.

The protocol is deliberately small and data-only. A client sends one canonical JSON request on standard input and accepts one JSON response on standard output. The executable is selected by an application-owned allowlist; neither a response nor an artifact can influence the command line. Every inspection performs a capability handshake before the artifact request.

This is process isolation, not an operating-system sandbox. An allowlisted program still has the filesystem and network privileges of the current user. POSIX hosts receive best-effort CPU, address-space, file-size, and descriptor limits; Windows receives parent-enforced wall-clock and output limits. Exact paths and optional SHA-256 pins are checked immediately before launch, but a hostile actor able to replace files concurrently could still exploit a TOCTOU window. Only locally trusted inspectors should ever be allowlisted.

InspectorProtocolClient

Launch allowlisted inspectors through the v1 JSON subprocess protocol.

diagnostic(inspector_id)

Check path and pins without running third-party code.

capabilities(inspector_id)

Negotiate and validate the capabilities of one allowlisted inspector.

inspect(inspector_id, artifact, *, capability, options=None)

Negotiate a capability, then inspect one bounded regular file.

InspectorAllowlist

Immutable lookup table of commands explicitly trusted by the caller.

get(inspector_id)

Return an allowlisted command or fail without launching a process.

InspectorExecutable dataclass

One exact command prefix admitted to the inspector allowlist.

arguments are static, application-controlled arguments. If an interpreter executes a script from those arguments, pin that script with support_files so integrity checks cover more than the interpreter.

command property

Return the immutable command prefix; no request data is appended.

InspectorFilePin dataclass

A support file whose content is trusted by SHA-256.

InspectorLimits dataclass

Budgets applied independently to each protocol exchange.

InspectorCapabilities dataclass

Validated identity and capabilities reported by one process.

InspectorCapability dataclass

Evidence contract declared during capability negotiation.

ExternalInspectionResult dataclass

Validated observations returned by an allowlisted external inspector.

JATS and RO-Crate

Deterministic JATS 1.4 and RO-Crate 1.3 metadata exports.

submission_manifest_to_jats(manifest, *, group_id='researchplot-figures')

Return a JATS 1.4 fig-group fragment for submission figures.

Captions and alt text are exported only when present; missing prose is not invented. Paths become XLink references and no referenced file is read.

submission_manifest_to_ro_crate(manifest, *, name='ResearchPlot submission evidence', description='Reproducible figure artifacts and provenance generated by ResearchPlot.', license=None, creators=())

Return a flat RO-Crate 1.3 JSON-LD metadata graph.

write_ro_crate_metadata(crate, path, *, overwrite=False)

Write canonical RO-Crate JSON, exclusively unless overwrite is explicit.

HTML and local workspace

rp.write_html_report(report, "build/report.html")
server, info = rp.create_server(port=0)
print(info.url)

Self-contained, offline HTML compliance reports.

SerializableReport

Bases: Protocol

Structural contract accepted by :func:render_html_report.

render_html_report(reports, *, title='ResearchPlot compliance report')

Render one or more reports as a self-contained, offline HTML document.

write_html_report(reports, path, *, title='ResearchPlot compliance report')

Write a self-contained report using an atomic same-directory replacement.

Privacy-preserving local browser workspace for ResearchPlot.

The server deliberately uses only the standard library and binds to the IPv4 loopback interface. Browser uploads are written to a private temporary directory, inspected by the same engine as the Python and CLI APIs, and removed before the response is returned.

ServerInfo dataclass

Connection details for a running local workspace.

LocalWebError

Bases: RuntimeError

Raised when the local preflight server cannot be started safely.

create_server(*, host='127.0.0.1', port=0)

Create a loopback-only local workspace server without starting it.

serve(*, port=0, open_browser=True)

Run the local preflight workspace until interrupted.

The returned :class:ServerInfo is mainly useful to callers that stop the server from another thread. CLI use blocks until Ctrl+C.

Environment provenance

provenance = dict(rp.collect_environment_provenance())

The tuple contains stable library/runtime/backend/font-setting/LaTeX keys and an rcParams digest. It intentionally omits usernames, hostnames, and filesystem paths.

Compatibility API

target = rp.target(
    "nature@2026.08.0",
    role="main",
    width="single",
    content="line-art",
)
live = target.validate(fig)
saved = target.audit("figure.pdf")
result = target.export(fig, "figure.pdf", policy="complete")

Resolved submission targets: the primary ResearchPlot 1.0 workflow.

Target dataclass

A resolved profile plus all metadata needed to select conditional rules.

style(*, latex=False, overrides=None)

Create a reversible Matplotlib style context for this target.

validate(fig, *, attestations=None)

Evaluate all applicable live-figure rules.

audit(path, *, attestations=None)

Inspect an exported artifact and evaluate file-phase rules.

plan_export(*, formats=None, preferred=None)

Return a no-write ResearchPlot 2 export plan.

Planning selects a single deterministic preferred representation when formats are omitted. The legacy :meth:export method intentionally retains its 1.x implicit multi-format behavior until the next major API boundary.

export(fig, target_path, *, formats=None, policy=Policy.COMPLETE, dpi=None, overwrite=False, attestations=None, metadata=None, **savefig_kwargs)

Transactionally export and post-audit this target.

target(profile, *, role=FigureRole.MAIN, width=None, content=ContentKind.DATA_VISUALIZATION)

Resolve an immutable profile revision into a submission target.

researchplot.plots is loaded lazily only when a deprecated plotting name is used. Install [plots] for its optional NumPy/pandas/Seaborn/SciPy/scikit-learn integrations.

Exceptions and serialization

Invalid project/profile/configuration input, unsafe artifact input, parser failures, resource limits, and unavailable operational capabilities are exceptions. Policy exceptions retain their report or assessment. Do not catch a broad exception merely to force publication.

to_dict() returns JSON-compatible values and stable enum strings. Human terminal phrasing may improve without a schema change. See report and manifest formats.