Index

🤖 AI-Generated Content

This documentation was generated with AI assistance and is still being audited. Some, or potentially a lot, of this information may be inaccurate. Learn more.

flavor ¶

FlavorPack core package exports and helper utilities.

Classes¶

BuildError ¶

Bases: FlavorException

Raised for errors during the package build process.

VerificationError ¶

Bases: FlavorException

Raised for errors during package verification.

Functions¶

build_package_from_manifest ¶

build_package_from_manifest(
    manifest_path: Path,
    output_path: Path | None = None,
    launcher_bin: Path | None = None,
    builder_bin: Path | None = None,
    strip_binaries: bool = False,
    show_progress: bool = False,
    private_key_path: Path | None = None,
    public_key_path: Path | None = None,
    key_seed: str | None = None,
) -> list[Path]

Build a PSPF package from a manifest file.

This is the main entry point for building FlavorPack packages programmatically. It reads a pyproject.toml or JSON manifest, resolves dependencies, creates a Python virtual environment, and assembles everything into a single .psp executable.

Parameters:

Name	Type	Description	Default
`manifest_path`	`Path`	Path to pyproject.toml or manifest.json file	required
`output_path`	`Path \| None`	Custom output path (default: dist/{package_name}.psp)	`None`
`launcher_bin`	`Path \| None`	Path to specific launcher binary (auto-selected if None)	`None`
`builder_bin`	`Path \| None`	Path to specific builder binary (auto-selected if None)	`None`
`strip_binaries`	`bool`	Strip debug symbols from launcher to reduce size	`False`
`show_progress`	`bool`	Display progress bars during build process	`False`
`private_key_path`	`Path \| None`	Path to Ed25519 private key in PEM format for signing	`None`
`public_key_path`	`Path \| None`	Path to Ed25519 public key in PEM format for signing	`None`
`key_seed`	`str \| None`	Deterministic seed for reproducible key generation (CI/CD)	`None`

Returns:

Type	Description
`list[Path]`	List containing the Path to the created .psp package file

Raises:

Type	Description
`ValueError`	If required manifest fields are missing
`BuildError`	If package build fails

Example

from pathlib import Path
from flavor import build_package_from_manifest

# Basic usage
packages = build_package_from_manifest(
    manifest_path=Path("pyproject.toml")
)
print(f"Created: {packages[0]}")

# With signing
packages = build_package_from_manifest(
    manifest_path=Path("pyproject.toml"),
    private_key_path=Path("keys/private.key"),
    public_key_path=Path("keys/public.key"),
)

Source code in flavor/package.py

def build_package_from_manifest(
    manifest_path: Path,
    output_path: Path | None = None,
    launcher_bin: Path | None = None,
    builder_bin: Path | None = None,
    strip_binaries: bool = False,
    show_progress: bool = False,
    private_key_path: Path | None = None,
    public_key_path: Path | None = None,
    key_seed: str | None = None,
) -> list[Path]:
    """Build a PSPF package from a manifest file.

    This is the main entry point for building FlavorPack packages programmatically.
    It reads a pyproject.toml or JSON manifest, resolves dependencies, creates a
    Python virtual environment, and assembles everything into a single .psp executable.

    Args:
        manifest_path: Path to pyproject.toml or manifest.json file
        output_path: Custom output path (default: dist/{package_name}.psp)
        launcher_bin: Path to specific launcher binary (auto-selected if None)
        builder_bin: Path to specific builder binary (auto-selected if None)
        strip_binaries: Strip debug symbols from launcher to reduce size
        show_progress: Display progress bars during build process
        private_key_path: Path to Ed25519 private key in PEM format for signing
        public_key_path: Path to Ed25519 public key in PEM format for signing
        key_seed: Deterministic seed for reproducible key generation (CI/CD)

    Returns:
        List containing the Path to the created .psp package file

    Raises:
        ValueError: If required manifest fields are missing
        BuildError: If package build fails

    Example:
        ```python
        from pathlib import Path
        from flavor import build_package_from_manifest

        # Basic usage
        packages = build_package_from_manifest(
            manifest_path=Path("pyproject.toml")
        )
        print(f"Created: {packages[0]}")

        # With signing
        packages = build_package_from_manifest(
            manifest_path=Path("pyproject.toml"),
            private_key_path=Path("keys/private.key"),
            public_key_path=Path("keys/public.key"),
        )
        ```
    """
    manifest_type = "json" if manifest_path.suffix == ".json" else "toml"

    if manifest_type == "json":
        config_data = _parse_json_manifest(manifest_path)
    else:
        config_data = _parse_toml_manifest(manifest_path)

    manifest_dir = manifest_path.parent.absolute()
    output_flavor_path = _determine_output_path(output_path, manifest_dir, config_data["package_name"])
    private_key_path, public_key_path = _setup_key_paths(
        private_key_path, public_key_path, manifest_dir, key_seed
    )

    # Pass CLI scripts to build config
    config_data["build_config"]["cli_scripts"] = config_data["cli_scripts"]

    orchestrator = _create_orchestrator(
        config_data,
        manifest_dir,
        output_flavor_path,
        private_key_path,
        public_key_path,
        launcher_bin,
        builder_bin,
        strip_binaries,
        show_progress,
        key_seed,
        manifest_type,
    )
    orchestrator.build_package()
    return [output_flavor_path]

clean_cache ¶

clean_cache() -> None

Remove all cached FlavorPack work environments and build artifacts.

Deletes the ~/.cache/flavor/ directory and all its contents, including: - Extracted package work environments - Cached helper binaries - Build artifacts

This is useful for: - Freeing up disk space - Resolving cache corruption issues - Testing fresh package extractions

Example

from flavor import clean_cache

clean_cache()
print("Cache cleared successfully")

Source code in flavor/package.py

def clean_cache() -> None:
    """Remove all cached FlavorPack work environments and build artifacts.

    Deletes the ~/.cache/flavor/ directory and all its contents, including:
    - Extracted package work environments
    - Cached helper binaries
    - Build artifacts

    This is useful for:
    - Freeing up disk space
    - Resolving cache corruption issues
    - Testing fresh package extractions

    Example:
        ```python
        from flavor import clean_cache

        clean_cache()
        print("Cache cleared successfully")
        ```
    """
    cache_dir = Path.home() / ".cache" / "flavor"
    if cache_dir.exists():
        safe_rmtree(cache_dir)

verify_package ¶

verify_package(package_path: Path) -> dict[str, Any]

Verify the integrity and signature of a PSPF package.

Validates the package structure, checksums, and cryptographic signatures to ensure the package hasn't been tampered with.

Parameters:

Name	Type	Description	Default
`package_path`	`Path`	Path to the .psp package file to verify	required

Returns:

Type	Description
`dict[str, Any]`	Dictionary containing verification results with keys: - 'valid' (bool): Overall verification status - 'signature_valid' (bool): Signature verification result - 'checksums_valid' (bool): Checksum verification result - 'format_valid' (bool): Format validation result - 'errors' (list): List of any errors encountered

Raises:

Type	Description
`VerificationError`	If verification fails critically

Example

from pathlib import Path
from flavor import verify_package

result = verify_package(Path("myapp.psp"))
if result['valid']:
else:
    print(f"❌ Verification failed: {result['errors']}")

Source code in flavor/package.py

def verify_package(package_path: Path) -> dict[str, Any]:
    """Verify the integrity and signature of a PSPF package.

    Validates the package structure, checksums, and cryptographic signatures
    to ensure the package hasn't been tampered with.

    Args:
        package_path: Path to the .psp package file to verify

    Returns:
        Dictionary containing verification results with keys:
            - 'valid' (bool): Overall verification status
            - 'signature_valid' (bool): Signature verification result
            - 'checksums_valid' (bool): Checksum verification result
            - 'format_valid' (bool): Format validation result
            - 'errors' (list): List of any errors encountered

    Raises:
        VerificationError: If verification fails critically

    Example:
        ```python
        from pathlib import Path
        from flavor import verify_package

        result = verify_package(Path("myapp.psp"))
        if result['valid']:
        else:
            print(f"❌ Verification failed: {result['errors']}")
        ```
    """
    from .verification import FlavorVerifier

    return FlavorVerifier.verify_package(package_path)