yapcad.package package

Subpackages

yapcad.package.analysis package

Submodules

yapcad.package.core module

Core .ycpkg packaging helpers.

class yapcad.package.core.PackageManifest(root: Path, data: Dict[str, ~typing.Any]=<factory>, manifest_name: str = 'manifest.yaml')[source]

Bases: object

Wrapper around the manifest document.

data: Dict[str, Any]

geometry_primary_path() → Path[source]

get_material(material_id: str) → Dict[str, Any] | None[source]: Get a specific material definition by ID.

get_materials() → Dict[str, Any][source]: Return the materials dictionary from the manifest.

classmethod load(package_path: Path | str) → PackageManifest[source]

manifest_name: str = 'manifest.yaml'

property manifest_path: Path

recompute_hashes(*, algorithm: str = 'sha256') → None[source]

root: Path

save() → None[source]

yapcad.package.core.add_geometry_file(manifest: PackageManifest, source: Path | str, *, dest_relative: str | None = None, purpose: str | None = None, category: str = 'derived', overwrite: bool = False, metadata: Dict[str, Any] | None = None) → Dict[str, Any][source]

Copy an external geometry file (e.g., STEP/STL) into the package and record it.

Parameters:

manifest – Loaded manifest wrapper.
source – Path to the external file that should be bundled.
dest_relative – Optional relative destination path inside the package root. Defaults to geometry/derived/<source.name>.
purpose – Optional description stored alongside the entry.
category – Manifest section to update. Supported: "derived" (default), "attachments".
overwrite – Allow replacing an existing file at the target location.
metadata – Additional key/value pairs merged into the manifest entry.

Returns:

The manifest entry dictionary that was inserted.

yapcad.package.core.create_package_from_entities(entities: Sequence[list], target_dir: Path | str, *, name: str, version: str, description: str | None = None, author: str | None = None, units: str | None = None, materials: Dict[str, Dict[str, Any]] | None = None, generator: Dict[str, Any] | None = None, overwrite: bool = False, hash_algorithm: str = 'sha256') → PackageManifest[source]

yapcad.package.core.load_geometry(manifest: PackageManifest) → List[list][source]

yapcad.package.signing module

Package signing and verification for yapCAD packages.

This module provides cryptographic signing and verification of .ycpkg packages using GPG or SSH keys. It enables individual contributors to sign packages without requiring a centralized authority.

Usage:

from yapcad.package.signing import sign_package, verify_package

# Sign with GPG sign_package(“my_design.ycpkg”, method=”gpg”, key_id=”ABCD1234”)

# Sign with SSH sign_package(“my_design.ycpkg”, method=”ssh”, key_path=”~/.ssh/id_ed25519”)

# Verify result = verify_package(“my_design.ycpkg”) if result.is_valid:

print(f”Verified: {result.trusted_signers} trusted signatures”)

class yapcad.package.signing.SignatureInfo(signer: str, method: SignatureMethod, key_id: str, timestamp: str, signature_file: str, status: VerificationStatus | None = None, error_message: str | None = None)[source]

Bases: object

Information about a single signature.

error_message: str | None = None

key_id: str

method: SignatureMethod

signature_file: str

signer: str

status: VerificationStatus | None = None

timestamp: str

class yapcad.package.signing.SignatureMethod(*values)[source]

Bases: Enum

Supported signature methods.

GPG = 'gpg'

SSH = 'ssh'

exception yapcad.package.signing.SigningError[source]

Bases: Exception

Error during signing operation.

exception yapcad.package.signing.VerificationError[source]

Bases: Exception

Error during verification operation.

class yapcad.package.signing.VerificationResult(package_path: str, manifest_hash: str, signatures: List[SignatureInfo] = <factory>, errors: List[str] = <factory>, warnings: List[str] = <factory>)[source]

Bases: object

Result of package verification.

errors: List[str]

property is_valid: bool: True if at least one trusted signature is valid.

manifest_hash: str

property overall_status: VerificationStatus: Overall verification status.

package_path: str

signatures: List[SignatureInfo]

property trusted_signers: int: Number of valid, trusted signatures.

property untrusted_signers: int: Number of valid but untrusted signatures.

warnings: List[str]

class yapcad.package.signing.VerificationStatus(*values)[source]

Bases: Enum

Verification result status.

ERROR = 'ERROR'

INVALID = 'INVALID'

VALID = 'VALID'

VALID_UNTRUSTED = 'VALID_UNTRUSTED'

yapcad.package.signing.list_signatures(package_path: str | Path) → List[SignatureInfo][source]

List all signatures on a package.

Parameters:: package_path – Path to .ycpkg package directory
Returns:: List of SignatureInfo for each signature

Sign a yapCAD package.

Parameters:

package_path – Path to .ycpkg package directory
method – “gpg” or “ssh”
key_id – GPG key ID (for GPG signing)
key_path – Path to SSH private key (for SSH signing)
add – If True, add signature without removing existing ones
signer_name – Override signer name in signature entry

Returns:

SignatureInfo for the new signature

Verify signatures on a yapCAD package.

Parameters:

package_path – Path to .ycpkg package directory
allowed_signers – Path to SSH allowed_signers file
gpg_keyring – Path to custom GPG keyring

Returns:

VerificationResult with status of all signatures

yapcad.package.validator module

Validation utilities for .ycpkg packages.

yapcad.package.validator.validate_package(path: Path | str, *, strict: bool = False) → Tuple[bool, List[str]][source]

Validate manifest and referenced artefacts.

Returns (is_valid, messages). Messages are strings with severity prefixes.

yapcad.package.viewer module

Interactive viewer for yapCAD .ycpkg packages.

yapcad.package.viewer.view_package(package_path: Path | str, *, strict: bool = False) → bool[source]: Validate a package and launch appropriate viewer.

Module contents

Public API for yapCAD .ycpkg package workflows.

class yapcad.package.AnalysisAdapter[source]

Bases: ABC

Base class for solver adapters.

name: str = 'analysis-adapter'

abstractmethod run(manifest, plan: AnalysisPlan, workspace: Path, **kwargs: Any) → AnalysisResult[source]: Execute the plan and return an AnalysisResult.

class yapcad.package.AnalysisPlan(plan_id: str, kind: str, backend: str, name: str | None = None, description: str | None = None, geometry: Dict[str, ~typing.Any]=<factory>, materials: Dict[str, ~typing.Any]=<factory>, loads: Dict[str, ~typing.Any]]=<factory>, boundary_conditions: Dict[str, ~typing.Any]]=<factory>, acceptance: Dict[str, ~typing.Any]=<factory>, backend_options: Dict[str, ~typing.Any]=<factory>, execution: ExecutionConfig = <factory>, attachments: Dict[str, ~typing.Any]]=<factory>, metadata: Dict[str, ~typing.Any]=<factory>, raw: Dict[str, ~typing.Any]=<factory>)[source]

Bases: object

Representation of a validation/analysis plan loaded from YAML.

acceptance: Dict[str, Any]

attachments: List[Dict[str, Any]]

backend: str

backend_options: Dict[str, Any]

boundary_conditions: List[Dict[str, Any]]

description: str | None = None

execution: ExecutionConfig

geometry: Dict[str, Any]

kind: str

loads: List[Dict[str, Any]]

materials: Dict[str, Any]

metadata: Dict[str, Any]

name: str | None = None

property normalized_backend: str

plan_id: str

raw: Dict[str, Any]

class yapcad.package.AnalysisResult(plan_id: str, status: str, metrics: Dict[str, ~typing.Any]=<factory>, summary: Dict[str, ~typing.Any]=<factory>, artifacts: Dict[str, ~typing.Any]]=<factory>, summary_path: Path | None = None, backend: str | None = None, timestamp: str | None = None, notes: str | None = None)[source]

Bases: object

Container for results emitted by analysis adapters.

artifacts: List[Dict[str, Any]]

backend: str | None = None

metrics: Dict[str, Any]

notes: str | None = None

plan_id: str

status: str

summary: Dict[str, Any]

summary_path: Path | None = None

timestamp: str | None = None

to_manifest_entry(package_root: Path) → Dict[str, Any][source]

class yapcad.package.ExecutionConfig(mode: str = 'local', command: str | None = None, transport: str | None = None, host: str | None = None, workdir: str | None = None, env: Dict[str, str]=<factory>, options: Dict[str, ~typing.Any]=<factory>, license: Dict[str, ~typing.Any]=<factory>)[source]

Bases: object

Execution context for an analysis plan.

command: str | None = None

env: Dict[str, str]

host: str | None = None

property is_remote: bool

license: Dict[str, Any]

mode: str = 'local'

options: Dict[str, Any]

transport: str | None = None

workdir: str | None = None

class yapcad.package.PackageManifest(root: Path, data: Dict[str, ~typing.Any]=<factory>, manifest_name: str = 'manifest.yaml')[source]

Bases: object

Wrapper around the manifest document.

data: Dict[str, Any]

geometry_primary_path() → Path[source]

get_material(material_id: str) → Dict[str, Any] | None[source]: Get a specific material definition by ID.

get_materials() → Dict[str, Any][source]: Return the materials dictionary from the manifest.

classmethod load(package_path: Path | str) → PackageManifest[source]

manifest_name: str = 'manifest.yaml'

property manifest_path: Path

recompute_hashes(*, algorithm: str = 'sha256') → None[source]

root: Path

save() → None[source]

class yapcad.package.SignatureInfo(signer: str, method: SignatureMethod, key_id: str, timestamp: str, signature_file: str, status: VerificationStatus | None = None, error_message: str | None = None)[source]

Bases: object

Information about a single signature.

error_message: str | None = None

key_id: str

method: SignatureMethod

signature_file: str

signer: str

status: VerificationStatus | None = None

timestamp: str

class yapcad.package.SignatureMethod(*values)[source]

Bases: Enum

Supported signature methods.

GPG = 'gpg'

SSH = 'ssh'

exception yapcad.package.SigningError[source]

Bases: Exception

Error during signing operation.

class yapcad.package.VerificationResult(package_path: str, manifest_hash: str, signatures: List[SignatureInfo] = <factory>, errors: List[str] = <factory>, warnings: List[str] = <factory>)[source]

Bases: object

Result of package verification.

errors: List[str]

property is_valid: bool: True if at least one trusted signature is valid.

manifest_hash: str

property overall_status: VerificationStatus: Overall verification status.

package_path: str

signatures: List[SignatureInfo]

property trusted_signers: int: Number of valid, trusted signatures.

property untrusted_signers: int: Number of valid but untrusted signatures.

warnings: List[str]

class yapcad.package.VerificationStatus(*values)[source]

Bases: Enum

Verification result status.

ERROR = 'ERROR'

INVALID = 'INVALID'

VALID = 'VALID'

VALID_UNTRUSTED = 'VALID_UNTRUSTED'

yapcad.package.add_geometry_file(manifest: PackageManifest, source: Path | str, *, dest_relative: str | None = None, purpose: str | None = None, category: str = 'derived', overwrite: bool = False, metadata: Dict[str, Any] | None = None) → Dict[str, Any][source]

Copy an external geometry file (e.g., STEP/STL) into the package and record it.

Parameters:

manifest – Loaded manifest wrapper.
source – Path to the external file that should be bundled.
dest_relative – Optional relative destination path inside the package root. Defaults to geometry/derived/<source.name>.
purpose – Optional description stored alongside the entry.
category – Manifest section to update. Supported: "derived" (default), "attachments".
overwrite – Allow replacing an existing file at the target location.
metadata – Additional key/value pairs merged into the manifest entry.

Returns:

The manifest entry dictionary that was inserted.

yapcad.package.analyze_package(package_path: Path | str, plan_path: Path | str, *, status: str = 'pending') → Path[source]

Record analysis metadata for plan_path inside package_path.

This helper prepares the results directory, writes a summary.json placeholder, and updates the manifest validation.results block.

yapcad.package.available_backends() → Sequence[str][source]

yapcad.package.create_package_from_entities(entities: Sequence[list], target_dir: Path | str, *, name: str, version: str, description: str | None = None, author: str | None = None, units: str | None = None, materials: Dict[str, Dict[str, Any]] | None = None, generator: Dict[str, Any] | None = None, overwrite: bool = False, hash_algorithm: str = 'sha256') → PackageManifest[source]

yapcad.package.list_signatures(package_path: str | Path) → List[SignatureInfo][source]

List all signatures on a package.

Parameters:: package_path – Path to .ycpkg package directory
Returns:: List of SignatureInfo for each signature

yapcad.package.load_analysis_plan(path: Path | str) → AnalysisPlan: Load a YAML analysis plan and return the normalised AnalysisPlan.

yapcad.package.load_geometry(manifest: PackageManifest) → List[list][source]

yapcad.package.register_backend(name: str, adapter_cls: Type[AnalysisAdapter]) → None[source]

Sign a yapCAD package.

Parameters:

package_path – Path to .ycpkg package directory
method – “gpg” or “ssh”
key_id – GPG key ID (for GPG signing)
key_path – Path to SSH private key (for SSH signing)
add – If True, add signature without removing existing ones
signer_name – Override signer name in signature entry

Returns:

SignatureInfo for the new signature

yapcad.package.validate_package(path: Path | str, *, strict: bool = False) → Tuple[bool, List[str]][source]

Validate manifest and referenced artefacts.

Returns (is_valid, messages). Messages are strings with severity prefixes.

Verify signatures on a yapCAD package.

Parameters:

package_path – Path to .ycpkg package directory
allowed_signers – Path to SSH allowed_signers file
gpg_keyring – Path to custom GPG keyring

Returns:

VerificationResult with status of all signatures

yapcad.package.view_package(package_path, *, strict: bool = False)[source]: Import and invoke the interactive viewer lazily.