fastsandpm.manifest API

Module for package manifest handling and parsing.

This module provides data models and functions for working with FastSandPM manifest files (proj.toml). It handles parsing, validation, and representation of package metadata, dependencies, and registry configurations.

Classes:

ManifestNotFoundError: Exception raised when manifest file is not found.
ManifestParseError: Exception raised when manifest parsing fails.
Package: Package metadata (name, version, description, authors).
Dependencies: Collection of package dependencies.
Manifest: The complete manifest model.

Functions:

get_manifest(): Load and parse a manifest from a repository path.
get_manifest_from_bytes(): Parse a manifest from raw bytes content.

Constants:

MANIFEST_FILENAME: The default manifest filename (“proj.toml”).

Example

>>> from fastsandpm.manifest import get_manifest
>>> manifest = get_manifest("./my-project")
>>> print(manifest.package.name)
'my-package'

Module Attributes

manifest.MANIFEST_FILENAME = 'proj.toml'

Functions

fastsandpm.manifest.get_manifest(path: PathLike) → Manifest[source]

Load and parse a manifest from a repository path.

Looks for a proj.toml file in the specified directory, parses it, and returns a Manifest object. Relative paths in path dependencies are resolved to absolute paths relative to the manifest file’s directory.

Parameters:

path – Path to the repository directory containing the proj.toml file.

Returns:

The parsed Manifest object with resolved path dependencies.

Raises:

ManifestNotFoundError – If the proj.toml file does not exist at the path.
ManifestParseError – If the TOML file is malformed or doesn’t match the expected manifest schema.

Example

>>> import pathlib
>>> import fastsandpm
>>> manifest = fastsandpm.get_manifest(pathlib.Path("some/repo/path"))
>>> print(manifest.package.name)
'my-package'

fastsandpm.manifest.get_manifest_from_bytes(content: bytes, source: str = '<bytes>') → Manifest[source]

Parse a manifest from raw bytes content.

This function is useful for parsing manifest content that has been fetched from a remote source (e.g., via git archive) without writing to disk.

Parameters:

content – The raw bytes content of a proj.toml file.
source – A string identifying the source of the content (for error messages).

Returns:

The parsed Manifest object.

Raises:

ManifestParseError – If the TOML content is malformed or doesn’t match the expected manifest schema.

Example

>>> content = b'[package]\nname = "my-pkg"\nversion = "1.0.0"\n...'
>>> manifest = get_manifest_from_bytes(content, source="git://repo")
>>> print(manifest.package.name)
'my-pkg'

Classes

class fastsandpm.manifest.Dependencies(root: RootModelRootType = PydanticUndefined)[source]

Bases: RootModel[list[Union[PackageIndexRequirement, PathRequirement, CommitGitRequirement, BranchGitRequirement, TaggedGitRequirement, VersionedGitRequirement, GitRequirement]]]

A collection of package dependencies.

This class handles parsing dependencies from various TOML formats into the appropriate dependency type objects. It provides list-like access to the underlying dependency collection.

Supported TOML formats:

Simple string: name = "version"
Registry format: name = {version = "1.0.0"}
Git format: name = {git = "url", ...}
Path format: name = {path = "./local/path"}

The model validator automatically converts dictionary-style TOML dependencies into the correct dependency type based on the keys present.

Example TOML:

[dependencies]

my-lib = "1.0.0"
other_lib = {git = "https://github.com/username/repo.git", tag = "v1.0.0"}

Example Usage:

>>> deps = manifest.dependencies
>>> for dep in deps:
...     print(dep.name)
>>> specific_dep = deps.get_by_name("my-lib")

See also

Pydantic RootModel for details on the base class and its methods.

classmethod parse_dependencies(data: Any) → Any[source]

Parse dependency data from various formats.

Handles conversion from TOML-style dependency specifications to the internal dependency model format.

Parameters:: data – Raw dependency data, either as a dict (from TOML) or list.
Returns:: A list of dependency dictionaries ready for model instantiation.

Examples

Input formats supported: - {“name”: “foo”, “version”: “1.0.0”} -> [{“name”: “foo”, …}] - {“foo”: “1.0.0”} -> [{“name”: “foo”, “version”: “1.0.0”}] - {“foo”: {“git”: “url”}} -> [{“name”: “foo”, “git”: “url”}] - {“foo”: {“path”: “./path”}} -> [{“name”: “foo”, “path”: “./path”}]

Append a dependency to the collection.

Parameters:: object – The dependency to append to the end of the collection.

Get a dependency by its name.

Parameters:: name – The name of the dependency to find.
Returns:: The dependency with the specified name, or None if not found.

Insert a dependency at a specific position.

Parameters:

index – The position where the dependency should be inserted.
object – The dependency to insert into the collection.

validate_unique_names() → Self[source]

Validate that all dependency names are unique.

Raises:: ValueError – If duplicate dependency names are found.
Returns:: The validated model instance.
Return type:: Self

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fastsandpm.manifest.Manifest(*, package: Package, dependencies: Dependencies = <factory>, optional_dependencies: dict[str, ~fastsandpm.manifest.Dependencies]=<factory>, registries: Registries = <factory>)[source]

Bases: BaseModel

The complete package manifest representing a proj.toml file.

A manifest contains all the information needed to build, distribute, and manage dependencies for a FastSandPM package. It includes package metadata, required and optional dependencies, and registry configurations.

Example TOML:

[package]
name = "my-package"
version = "1.0.0"
description = "My HDL package"

[dependencies]
some-lib = "^1.2.0"

[optional_dependencies.dev]
test-lib = "1.0.0"

See also

Package for package metadata details.
Dependencies for dependency collection details.
Pydantic BaseModel for details on the parent BaseModel class.

classmethod parse_optional_dependencies(data: Any) → Any[source]

Parse optional_dependencies from various TOML formats.

Handles conversion from TOML-style optional dependency specifications: - List format: [optional_dependencies] group = [{name=”foo”, version=”1.0”}] - Table format: [optional_dependencies.group] foo = “1.0”

Parameters:: data – Raw manifest data from TOML parsing.
Returns:: The data with optional_dependencies converted to list format.

dependencies: Dependencies: Required package dependencies.

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

optional_dependencies: dict[str, Dependencies]: Named groups of optional dependencies.

package: Package: The package metadata (name, version, description).

registries: Registries: Package registries for dependency resolution.

class fastsandpm.manifest.Package(*, name: str, version: ~typing.Annotated[~fastsandpm.versioning.library_version.LibraryVersion, ~pydantic.functional_validators.PlainValidator(func=~fastsandpm.manifest.<lambda>, json_schema_input_type=str), ~pydantic.functional_serializers.PlainSerializer(func=~fastsandpm.manifest.<lambda>, return_type=str, when_used=always), ~pydantic.json_schema.WithJsonSchema(json_schema={'type': 'string'}, mode=None)], description: str = '', flist: ~pathlib.Path = <factory>, authors: str | list[str] | dict[str, str] | None = None, readme: ~pathlib.Path | None = None)[source]

Bases: BaseModel

Package metadata from a manifest file.

Contains the core package information including name, version, and description. Authors and readme path are optional fields.

Example TOML:

[package]
name = "package_name"
version = "1.2.3-a4"
description = "A sample package"

authors = "Jane Doe <jdoe@doelife.com>"
readme = "README.txt"