Base Types

Base building blocks that other result types build on. These provide core functionality for tracking errors, warnings, loading operations, and validation results.

Base Collections

ci.transparency.cwe.types.base.collections

Collections for tracking files, categories, and duplicates in the civic transparency CWE types module.

This module provides dataclasses for: - FileCollection: tracking processed, failed, and skipped files. - CategoryCollection: tracking category statistics. - DuplicateCollection: tracking duplicate IDs and their associated file paths.

__all__ = ['FrameworkStatsDict', 'RelationshipMapDict', 'RelationshipDepthsDict', 'RelationshipTypesDict', 'CategoryCollection', 'DuplicateCollection', 'FileCollection', 'FrameworkCollection', 'ReferenceCollection'] module-attribute

FrameworkStatsDict = dict[str, int]

RelationshipDepthsDict = dict[str, int]

RelationshipMapDict = dict[str, list[str]]

RelationshipTypesDict = dict[str, int]

CategoryCollection dataclass

Tracks statistics for categories.

Attributes

category_stats : dict[str, int] Dictionary mapping category names to their counts.

category_count property

Return the number of categories tracked in the collection.

most_common_category property

Return the most common category based on the highest count.

Returns

str or None The category with the highest count, or None if there are no categories.

DuplicateCollection dataclass

Tracks duplicate IDs and their associated file paths.

Attributes

duplicate_ids : dict[str, list[Path]] Dictionary mapping duplicate IDs to lists of file paths where duplicates were found.

duplicate_count property

Return the number of duplicate IDs tracked in the collection.

Returns

int The number of duplicate IDs.

has_duplicates property

Return True if there are any duplicate IDs, otherwise False.

FileCollection dataclass

Tracks processed, failed, and skipped files.

Attributes

processed_files : list[Path] list of files that have been processed. failed_files : list[Path] list of files that failed to process. skipped_files : list[Path] list of files that were skipped.

failed_file_count property

Return the number of failed files.

processed_file_count property

Return the number of processed files.

skipped_file_count property

Return the number of skipped files.

total_files property

Return the total number of files (processed, failed, skipped).

FrameworkCollection dataclass

Tracks statistics for frameworks.

Could be reused for any domain that categorizes by framework.

framework_count property

Return the number of frameworks tracked.

most_common_framework property

Return the most common framework based on highest count.

add_framework(framework)

Add or increment a framework count.

ReferenceCollection dataclass

Tracks references between items and their validity.

Could be reused for any domain that has inter-item references.

has_invalid_references property

True if there are invalid references.

has_orphaned_items property

True if there are orphaned items.

invalid_reference_count property

Number of invalid references.

orphaned_item_count property

Number of items with no references.

total_references_count property

Total number of references tracked.

add_invalid_reference(reference_desc)

Add an invalid reference.

add_orphaned_item(item_id)

Add an orphaned item.

add_reference(from_item, to_item)

Add a reference between items.

options: showsource: false show_signature: true group_by_category: true filters: - "!^"

Base Counts

ci.transparency.cwe.types.base.counts

Core counting components for transparency CWE types.

This module provides dataclasses for tracking counts of loaded, validated, and processed items: - LoadingCounts: Tracks successfully loaded and failed items. - ValidationCounts: Tracks passed and failed validations. - ProcessingCounts: Tracks processed and skipped items.

__all__ = ['LoadingCounts', 'ProcessingCounts', 'ValidationCounts'] module-attribute

LoadingCounts dataclass

Tracks the number of successfully loaded and failed items.

Attributes

loaded_count : int Number of items successfully loaded. failed_count : int Number of items that failed to load.

is_successful property

Return True if there are no failed validations, otherwise False.

success_rate property

Return the rate of successful loads as a float between 0 and 1.

total_attempted property

Return the total number of attempted loads (successful + failed).

ProcessingCounts dataclass

Tracks the number of processed and skipped items.

Attributes

processed_count : int Number of items that have been processed. skipped_count : int Number of items that have been skipped.

total_encountered property

Return the total number of encountered items (processed + skipped).

ValidationCounts dataclass

Tracks the number of passed and failed validations.

Attributes

passed_count : int Number of items that passed validation. failed_count : int Number of items that failed validation.

is_successful property

Return True if there are no failed validations, otherwise False.

pass_rate property

Return the rate of passed validations as a float between 0 and 1.

total_validated property

Return the total number of validated items (passed + failed).

options: showsource: false show_signature: true group_by_category: true filters: - "!^"

Base Errors

ci.transparency.cwe.types.base.errors

Enhanced base error types for transparency operations.

Provides comprehensive base exception classes that capture common patterns across all transparency domains (CWE, schema validation, standards processing).

Design principles

• Flexible: supports optional context fields without requiring all errors to use them
• Contextual: captures progress, operations, resources, files, validation, and abort context
• Consistent: maintains uniform formatting with " | " separator
• Slotted: minimal memory overhead with slots
• Hierarchical: specific base classes for common operation types

Core error hierarchy

• BaseTransparencyError: Root exception with flexible context support
• OperationError: Operations with progress tracking (batch, phase processing)
• ResourceError: Resource-constrained operations (timeouts, limits)
• ValidationError: Validation operations with rule/schema context
• FileError: File-based operations with path context

All errors use consistent formatting: "message | Context1: value | Context2: value" Context is only included when relevant fields are populated.

__all__ = ['BaseTransparencyError', 'OperationError', 'ResourceError', 'ValidationError', 'FileError', 'LoadingError', 'ParsingError', 'ConfigurationError', 'TransparencyTimeoutError', 'AbortedError', 'NetworkError'] module-attribute

AbortedError

Bases: BaseTransparencyError

Operation was aborted before completion.

BaseTransparencyError

Bases: Exception

Enhanced base exception for all transparency operations.

Provides flexible context tracking for common error patterns without requiring all errors to specify every possible context field.

get_context_parts()

Get contextual information parts for error formatting.

Returns context in order of importance: 1. Operation identification (phase, operation, stage) 2. Progress information (processed/total counts) 3. Resource information (timeouts, limits) 4. File/item context 5. Validation context 6. Error flow context (abort reason, error code)

Returns:

Type	Description
list[str]	List of context strings (e.g., ["Phase: validation", "Progress: 150/500"])

ConfigurationError

Bases: BaseTransparencyError

Configuration is invalid or incomplete.

FileError

Bases: BaseTransparencyError

Base exception for file-based operations.

Convenient base for file loading, parsing, and other file-related errors.

LoadingError

Bases: FileError

File could not be loaded.

NetworkError

Bases: BaseTransparencyError

Network operation failed.

OperationError

Bases: BaseTransparencyError

Base exception for operations with progress tracking.

Convenient base for batch processing, phase validation, and other operations that process multiple items with progress tracking.

ParsingError

Bases: FileError

File could not be parsed.

ResourceError

Bases: BaseTransparencyError

Base exception for resource-constrained operations.

Convenient base for timeout, memory, disk space, and other resource-related errors.

TransparencyTimeoutError

Bases: ResourceError

Operation timed out.

ValidationError

Bases: BaseTransparencyError

Base exception for validation operations.

Convenient base for schema validation, rule checking, and other validation-related errors.

options: showsource: false show_signature: true group_by_category: true filters: - "!^"

Base Messages

ci.transparency.cwe.types.base.messages

Define message collection classes for error, warning, and informational messages.

It provides: - MessageCollection: a dataclass for collecting and counting error, warning, and info messages.

__all__ = ['MessageCollection'] module-attribute

MessageCollection dataclass

Collects error, warning, and info messages.

Attributes

errors : list[str] list of error messages. warnings : list[str] list of warning messages. infos : list[str] list of informational messages.

error_count property

Return the number of error messages.

has_errors property

Return True if there are any error messages, otherwise False.

has_warnings property

Return True if there are any warning messages, otherwise False.

info_count property

Return the number of informational messages.

total_messages property

Return the total number of messages (errors, warnings, infos).

warning_count property

Return the number of warning messages.

_empty_str_list()

Return an empty list of strings (for Pyright).

options: showsource: false show_signature: true group_by_category: true filters: - "!^"

Result Helpers

ci.transparency.cwe.types.base.result_helpers

Helpers for adding message methods to result classes.

This module provides a decorator to add error, warning, and info message methods to result classes.

T = TypeVar('T', bound=HasMessages) module-attribute

__all__ = ['HasMessages', 'with_message_methods'] module-attribute

HasMessages

Bases: Protocol

Protocol for result types that have a messages field.

MessageCollection dataclass

Collects error, warning, and info messages.

Attributes

errors : list[str] list of error messages. warnings : list[str] list of warning messages. infos : list[str] list of informational messages.

error_count property

Return the number of error messages.

has_errors property

Return True if there are any error messages, otherwise False.

has_warnings property

Return True if there are any warning messages, otherwise False.

info_count property

Return the number of informational messages.

total_messages property

Return the total number of messages (errors, warnings, infos).

warning_count property

Return the number of warning messages.

_add_message_to_result(result, level, message)

Add a message to any result with MessageCollection.

Internal helper that modifies the messages collection immutably.

with_message_methods(cls)

Add message methods to result classes.

Decorator that adds add_error(), add_warning(), and add_info() methods to any result class with a MessageCollection field.

options: showsource: false show_signature: true group_by_category: true filters: - "!^"

Schema

ci.transparency.cwe.types.base.schema

Defines schema metadata and statistics tracking for civic transparency.

This module provides: - FileTypeStatsDict: type alias for file type statistics. - SchemaCollection: dataclass for schema metadata and file type statistics.

__all__ = ['FileTypeStatsDict', 'SchemaCollection'] module-attribute

FileTypeStatsDict = dict[str, int]

SchemaCollection dataclass

Tracks schema metadata and statistics.

Could be reused for any domain that works with schemas.

file_type_count property

Number of different file types processed.

has_schema_metadata property

True if schema name and version are available.

add_file_type(file_type)

Add or increment a file type count.

with_metadata(schema_name, schema_version)

Return new collection with updated schema metadata.

options: showsource: false show_signature: true group_by_category: true filters: - "!^"