Skip to content

spec

🤖 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.psp.format_2025.spec

PSPF Build Specification - Immutable data structures for package building.

This module defines the core data structures used throughout the PSPF builder system, emphasizing immutability and functional programming patterns.

Classes

BuildOptions

Immutable build options controlling package generation.

These options affect how the package is built but not what goes into it.

Functions
with_compression 
with_compression(
    compression: str, level: int | None = None
) -> BuildOptions

Return new BuildOptions with updated compression settings.

Source code in flavor/psp/format_2025/spec.py 
79
80
81
82
83
84
def with_compression(self, compression: str, level: int | None = None) -> BuildOptions:
    """Return new BuildOptions with updated compression settings."""
    updates: dict[str, Any] = {"compression": compression}
    if level is not None:
        updates["compression_level"] = level
    return attrs.evolve(self, **updates)

BuildResult

Immutable result from a build operation.

Contains success status, errors, warnings, and metadata about the build.

Functions
add_error 
add_error(error: str) -> BuildResult

Return new BuildResult with additional error.

Source code in flavor/psp/format_2025/spec.py 
191
192
193
194
def add_error(self, error: str) -> BuildResult:
    """Return new BuildResult with additional error."""
    new_errors = [*self.errors, error]
    return attrs.evolve(self, errors=new_errors, success=False)
add_warning 
add_warning(warning: str) -> BuildResult

Return new BuildResult with additional warning.

Source code in flavor/psp/format_2025/spec.py 
196
197
198
199
def add_warning(self, warning: str) -> BuildResult:
    """Return new BuildResult with additional warning."""
    new_warnings = [*self.warnings, warning]
    return attrs.evolve(self, warnings=new_warnings)
has_errors 
has_errors() -> bool

Check if there are any errors.

Source code in flavor/psp/format_2025/spec.py 
183
184
185
def has_errors(self) -> bool:
    """Check if there are any errors."""
    return len(self.errors) > 0
has_warnings 
has_warnings() -> bool

Check if there are any warnings.

Source code in flavor/psp/format_2025/spec.py 
187
188
189
def has_warnings(self) -> bool:
    """Check if there are any warnings."""
    return len(self.warnings) > 0
with_metadata 
with_metadata(**kwargs: Any) -> BuildResult

Return new BuildResult with updated metadata.

Source code in flavor/psp/format_2025/spec.py 
201
202
203
204
def with_metadata(self, **kwargs: Any) -> BuildResult:
    """Return new BuildResult with updated metadata."""
    new_metadata = {**self.metadata, **kwargs}
    return attrs.evolve(self, metadata=new_metadata)

BuildSpec

Immutable build specification containing all information needed to build a package.

This is the central data structure that flows through the build process.

Functions
has_required_metadata 
has_required_metadata() -> bool

Check if required metadata fields are present.

Source code in flavor/psp/format_2025/spec.py 
150
151
152
153
154
155
156
157
158
159
160
def has_required_metadata(self) -> bool:
    """Check if required metadata fields are present."""
    if not self.metadata:
        return False

    # Check for package name (various possible locations)
    has_name = "name" in self.metadata or (
        "package" in self.metadata and "name" in self.metadata["package"]
    )

    return has_name
replace_slots 
replace_slots(slots: list[SlotMetadata]) -> BuildSpec

Return new BuildSpec with replaced slot list.

Completely replaces the existing slots.

Source code in flavor/psp/format_2025/spec.py 
134
135
136
137
138
139
140
def replace_slots(self, slots: list[SlotMetadata]) -> BuildSpec:
    """
    Return new BuildSpec with replaced slot list.

    Completely replaces the existing slots.
    """
    return attrs.evolve(self, slots=slots)
with_keys 
with_keys(keys: KeyConfig) -> BuildSpec

Return new BuildSpec with updated key configuration.

Source code in flavor/psp/format_2025/spec.py 
142
143
144
def with_keys(self, keys: KeyConfig) -> BuildSpec:
    """Return new BuildSpec with updated key configuration."""
    return attrs.evolve(self, keys=keys)
with_metadata 
with_metadata(**kwargs: Any) -> BuildSpec

Return new BuildSpec with updated metadata.

Merges provided kwargs with existing metadata.

Source code in flavor/psp/format_2025/spec.py 
107
108
109
110
111
112
113
114
def with_metadata(self, **kwargs: Any) -> BuildSpec:
    """
    Return new BuildSpec with updated metadata.

    Merges provided kwargs with existing metadata.
    """
    new_metadata = {**self.metadata, **kwargs}
    return attrs.evolve(self, metadata=new_metadata)
with_options 
with_options(options: BuildOptions) -> BuildSpec

Return new BuildSpec with updated build options.

Source code in flavor/psp/format_2025/spec.py 
146
147
148
def with_options(self, options: BuildOptions) -> BuildSpec:
    """Return new BuildSpec with updated build options."""
    return attrs.evolve(self, options=options)
with_slot 
with_slot(slot: SlotMetadata) -> BuildSpec

Return new BuildSpec with additional slot.

Appends the slot to the existing list.

Source code in flavor/psp/format_2025/spec.py 
116
117
118
119
120
121
122
123
def with_slot(self, slot: SlotMetadata) -> BuildSpec:
    """
    Return new BuildSpec with additional slot.

    Appends the slot to the existing list.
    """
    new_slots = [*self.slots, slot]
    return attrs.evolve(self, slots=new_slots)
with_slots 
with_slots(*slots: SlotMetadata) -> BuildSpec

Return new BuildSpec with multiple additional slots.

Appends all provided slots to the existing list.

Source code in flavor/psp/format_2025/spec.py 
125
126
127
128
129
130
131
132
def with_slots(self, *slots: SlotMetadata) -> BuildSpec:
    """
    Return new BuildSpec with multiple additional slots.

    Appends all provided slots to the existing list.
    """
    new_slots = [*self.slots, *slots]
    return attrs.evolve(self, slots=new_slots)

KeyConfig

Immutable key configuration for package signing.

Supports multiple key sources with clear priority: 1. Explicit keys (highest priority) 2. Deterministic from seed 3. Load from filesystem path 4. Generate ephemeral (default)

Functions
has_explicit_keys 
has_explicit_keys() -> bool

Check if explicit keys are provided.

Source code in flavor/psp/format_2025/spec.py 
40
41
42
def has_explicit_keys(self) -> bool:
    """Check if explicit keys are provided."""
    return self.private_key is not None and self.public_key is not None
has_path 
has_path() -> bool

Check if key path is provided.

Source code in flavor/psp/format_2025/spec.py 
48
49
50
def has_path(self) -> bool:
    """Check if key path is provided."""
    return self.key_path is not None
has_seed 
has_seed() -> bool

Check if deterministic seed is provided.

Source code in flavor/psp/format_2025/spec.py 
44
45
46
def has_seed(self) -> bool:
    """Check if deterministic seed is provided."""
    return self.key_seed is not None

PreparedSlot

Immutable representation of a slot that has been prepared for packaging.

Contains the processed data and metadata needed to write the slot.

Functions
get_data_to_write 
get_data_to_write() -> bytes

Get the actual data to write (compressed if available).

Source code in flavor/psp/format_2025/spec.py 
230
231
232
def get_data_to_write(self) -> bytes:
    """Get the actual data to write (compressed if available)."""
    return self.compressed_data if self.compressed_data else self.data
get_size 
get_size() -> int

Get the size of data to write.

Source code in flavor/psp/format_2025/spec.py 
234
235
236
def get_size(self) -> int:
    """Get the size of data to write."""
    return len(self.get_data_to_write())
with_codec 
with_codec(
    compressed_data: bytes, operations: int
) -> PreparedSlot

Return new PreparedSlot with operations applied.

Source code in flavor/psp/format_2025/spec.py 
222
223
224
def with_codec(self, compressed_data: bytes, operations: int) -> PreparedSlot:
    """Return new PreparedSlot with operations applied."""
    return attrs.evolve(self, compressed_data=compressed_data, operations=operations)
with_offset 
with_offset(offset: int) -> PreparedSlot

Return new PreparedSlot with offset set.

Source code in flavor/psp/format_2025/spec.py 
226
227
228
def with_offset(self, offset: int) -> PreparedSlot:
    """Return new PreparedSlot with offset set."""
    return attrs.evolve(self, offset=offset)