artlink 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (44) hide show
  1. artlink/__init__.py +9 -0
  2. artlink/artifact.py +302 -0
  3. artlink/cli.py +85 -0
  4. artlink/cli_tools.py +123 -0
  5. artlink/domains/__init__.py +1 -0
  6. artlink/domains/common.py +158 -0
  7. artlink/examples/__init__.py +1 -0
  8. artlink/examples/domains/__init__.py +1 -0
  9. artlink/examples/domains/docs.py +89 -0
  10. artlink/examples/domains/hdl.py +135 -0
  11. artlink/examples/domains/ml.py +104 -0
  12. artlink/examples/domains/python.py +179 -0
  13. artlink/manifest.py +122 -0
  14. artlink/materialize.py +208 -0
  15. artlink/packages.py +158 -0
  16. artlink/registry.py +409 -0
  17. artlink/resolver.py +308 -0
  18. artlink/template.py +240 -0
  19. artlink/tests/fixtures/installed/share/artlink/demo-board/1.0.0/demo.xdc +1 -0
  20. artlink/tests/fixtures/installed/share/artlink/demo-board/1.0.0/manifest.yaml +10 -0
  21. artlink/tests/fixtures/installed/share/artlink/hdl-filter/2.0.0/filter.sv +2 -0
  22. artlink/tests/fixtures/installed/share/artlink/hdl-filter/2.0.0/manifest.yaml +13 -0
  23. artlink/tests/fixtures/installed/share/artlink/python-driver/0.1.0/manifest.yaml +10 -0
  24. artlink/tests/fixtures/projects/hardware-project.yaml +16 -0
  25. artlink/tests/fixtures/registry/hardware-registry.yaml +4 -0
  26. artlink/tests/fixtures/templates/hardware-build-inputs.yaml +24 -0
  27. artlink/tests/integration/test_artlink_cli.py +95 -0
  28. artlink/tests/integration/test_core_workflow.py +200 -0
  29. artlink/tests/integration/test_docs_profile.py +51 -0
  30. artlink/tests/integration/test_hardware_profile.py +70 -0
  31. artlink/tests/integration/test_ml_profile.py +56 -0
  32. artlink/tests/integration/test_python_profile.py +82 -0
  33. artlink/tests/test_all.py +5 -0
  34. artlink/tests/test_cli_tools.py +73 -0
  35. artlink/tests/test_manifest.py +207 -0
  36. artlink/tests/test_materialize.py +106 -0
  37. artlink/tests/test_registry.py +281 -0
  38. artlink/tests/test_resolver.py +189 -0
  39. artlink/tests/test_template.py +102 -0
  40. artlink-0.1.0.dist-info/METADATA +577 -0
  41. artlink-0.1.0.dist-info/RECORD +44 -0
  42. artlink-0.1.0.dist-info/WHEEL +4 -0
  43. artlink-0.1.0.dist-info/entry_points.txt +2 -0
  44. artlink-0.1.0.dist-info/licenses/LICENSE +201 -0
artlink/__init__.py ADDED
@@ -0,0 +1,9 @@
1
+ from .artifact import *
2
+ from .manifest import *
3
+ from .materialize import *
4
+ from .packages import *
5
+ from .registry import *
6
+ from .resolver import *
7
+ from .template import *
8
+
9
+ __version__ = "0.1.0"
artlink/artifact.py ADDED
@@ -0,0 +1,302 @@
1
+ from __future__ import annotations
2
+
3
+ import mimetypes
4
+ from pathlib import Path
5
+ from typing import Any, Literal
6
+
7
+ from ccflow.base import BaseModel
8
+ from pydantic import ConfigDict, Field, ValidationError, field_serializer, field_validator, model_validator
9
+
10
+ __all__ = (
11
+ "ArtlinkError",
12
+ "ManifestError",
13
+ "Digest",
14
+ "Capability",
15
+ "ArtifactInferenceIssue",
16
+ "Reference",
17
+ "Artifact",
18
+ "artifact_inference_issues",
19
+ "capability_from_value",
20
+ "has_capability",
21
+ )
22
+
23
+
24
+ class ArtlinkError(ValueError):
25
+ """Base error for artlink model and workflow failures."""
26
+
27
+
28
+ class ManifestError(ArtlinkError):
29
+ """Raised when manifest or artifact data is structurally invalid."""
30
+
31
+
32
+ class _ArtlinkModel(BaseModel):
33
+ def model_dump(self, *args: Any, **kwargs: Any) -> dict[str, Any]:
34
+ kwargs.setdefault("exclude_computed_fields", True)
35
+ return super().model_dump(*args, **kwargs)
36
+
37
+
38
+ class _ManifestModel(_ArtlinkModel):
39
+ def __init__(self, **data: Any) -> None:
40
+ try:
41
+ super().__init__(**data)
42
+ except ValidationError as exc:
43
+ raise ManifestError(str(exc)) from exc
44
+
45
+
46
+ class Digest(_ManifestModel):
47
+ model_config = ConfigDict(frozen=True)
48
+
49
+ algorithm: str
50
+ value: str
51
+
52
+ @field_validator("algorithm", "value")
53
+ @classmethod
54
+ def _validate_required_text(cls, value: str) -> str:
55
+ if not value:
56
+ raise ValueError("digest fields must not be empty")
57
+ return value
58
+
59
+
60
+ class Capability(_ManifestModel):
61
+ """A named capability that an artifact provides or requires."""
62
+
63
+ model_config = ConfigDict(frozen=True)
64
+
65
+ kind: str = ""
66
+ name: str
67
+ metadata: dict[str, Any] = Field(default_factory=dict)
68
+
69
+ @model_validator(mode="before")
70
+ @classmethod
71
+ def _from_shorthand(cls, data: Any) -> Any:
72
+ if isinstance(data, str):
73
+ return {"name": data}
74
+ return data
75
+
76
+ @field_validator("kind", "name", mode="before")
77
+ @classmethod
78
+ def _normalize_text(cls, value: Any) -> Any:
79
+ if value is None:
80
+ return ""
81
+ return value
82
+
83
+ @field_validator("name")
84
+ @classmethod
85
+ def _validate_name(cls, value: str) -> str:
86
+ if not value:
87
+ raise ValueError("capability name must not be empty")
88
+ return value
89
+
90
+ @property
91
+ def key(self) -> str:
92
+ if self.kind:
93
+ return f"{self.kind}:{self.name}"
94
+ return self.name
95
+
96
+
97
+ CapabilityValue = Capability | str | dict[str, Any]
98
+
99
+
100
+ class ArtifactInferenceIssue(_ArtlinkModel):
101
+ model_config = ConfigDict(frozen=True)
102
+
103
+ field: Literal["format", "media_type"]
104
+ declared_value: str
105
+ inferred_value: str
106
+ severity: Literal["warning"] = "warning"
107
+ message: str
108
+
109
+
110
+ class Reference(_ManifestModel):
111
+ model_config = ConfigDict(frozen=True)
112
+
113
+ kind: Literal["artifact", "manifest", "template", "package", "registry"]
114
+ target: str
115
+ version: str = ""
116
+ metadata: dict[str, Any] = Field(default_factory=dict)
117
+
118
+ @field_validator("target")
119
+ @classmethod
120
+ def _validate_target(cls, value: str) -> str:
121
+ if not value:
122
+ raise ValueError("reference target must not be empty")
123
+ return value
124
+
125
+
126
+ class Artifact(_ManifestModel):
127
+ """A packageable or consumable unit of content."""
128
+
129
+ model_config = ConfigDict(frozen=True)
130
+
131
+ id: str = ""
132
+ name: str = ""
133
+ path: Path | None = None
134
+ uri: str = ""
135
+ kind: str = ""
136
+ role: str
137
+ format: str = ""
138
+ media_type: str = ""
139
+ language: str = ""
140
+ provides: tuple[CapabilityValue, ...] = Field(default_factory=tuple)
141
+ requires: tuple[CapabilityValue, ...] = Field(default_factory=tuple)
142
+ digest: Digest | None = None
143
+ metadata: dict[str, Any] = Field(default_factory=dict)
144
+
145
+ @model_validator(mode="before")
146
+ @classmethod
147
+ def _infer_fields(cls, data: Any) -> Any:
148
+ if not isinstance(data, dict):
149
+ return data
150
+ inferred = dict(data)
151
+ location = inferred.get("path") or inferred.get("uri")
152
+ if location and not inferred.get("format"):
153
+ inferred_format = _infer_format(location)
154
+ if inferred_format:
155
+ inferred["format"] = inferred_format
156
+ if location and not inferred.get("media_type"):
157
+ media_type = _infer_media_type(location)
158
+ if media_type:
159
+ inferred["media_type"] = media_type
160
+ return inferred
161
+
162
+ @field_validator("path", mode="before")
163
+ @classmethod
164
+ def _normalize_empty_path(cls, value: Any) -> Any:
165
+ if value == "":
166
+ return None
167
+ return value
168
+
169
+ @field_validator("uri", "kind", "role", mode="before")
170
+ @classmethod
171
+ def _normalize_text(cls, value: Any) -> Any:
172
+ if value is None:
173
+ return ""
174
+ return value
175
+
176
+ @field_validator("role")
177
+ @classmethod
178
+ def _validate_required_text(cls, value: str) -> str:
179
+ if not value:
180
+ raise ValueError("artifact role must not be empty")
181
+ return value
182
+
183
+ @field_validator("provides", "requires", mode="before")
184
+ @classmethod
185
+ def _normalize_capabilities(cls, value: Any) -> tuple[CapabilityValue, ...]:
186
+ if value is None:
187
+ return ()
188
+ if isinstance(value, str | dict | Capability):
189
+ return (capability_from_value(value),)
190
+ return tuple(capability_from_value(item) for item in value)
191
+
192
+ @field_serializer("provides", "requires")
193
+ def _serialize_capabilities(self, value: tuple[CapabilityValue, ...]) -> list[str | dict[str, Any]]:
194
+ return [_dump_capability(capability_from_value(capability)) for capability in value]
195
+
196
+ @field_validator("provides", "requires")
197
+ @classmethod
198
+ def _validate_capabilities(cls, value: tuple[CapabilityValue, ...]) -> tuple[CapabilityValue, ...]:
199
+ return tuple(value)
200
+
201
+ @model_validator(mode="after")
202
+ def _validate_location(self) -> "Artifact":
203
+ if self.path is None and not self.uri:
204
+ raise ValueError("artifact must declare a path or uri")
205
+ return self
206
+
207
+ @property
208
+ def location(self) -> str:
209
+ if self.path is not None:
210
+ return self.path.as_posix()
211
+ return self.uri
212
+
213
+ @property
214
+ def display_id(self) -> str:
215
+ return self.id or self.name or self.location
216
+
217
+ @property
218
+ def inference_issues(self) -> tuple[ArtifactInferenceIssue, ...]:
219
+ return artifact_inference_issues(self)
220
+
221
+
222
+ def _infer_format(location: Any) -> str:
223
+ text = str(location).lower()
224
+ suffix_mappings = (
225
+ (".tar.gz", "tar.gz"),
226
+ (".tar.bz2", "tar.bz2"),
227
+ (".tar.xz", "tar.xz"),
228
+ (".whl", "wheel"),
229
+ )
230
+ for suffix, artifact_format in suffix_mappings:
231
+ if text.endswith(suffix):
232
+ return artifact_format
233
+ suffix = Path(text).suffix
234
+ if not suffix:
235
+ return ""
236
+ return suffix.removeprefix(".")
237
+
238
+
239
+ def _infer_media_type(location: Any) -> str:
240
+ media_type, _ = mimetypes.guess_type(str(location))
241
+ return media_type or ""
242
+
243
+
244
+ def artifact_inference_issues(artifact: Artifact) -> tuple[ArtifactInferenceIssue, ...]:
245
+ location = artifact.path or artifact.uri
246
+ if not location:
247
+ return ()
248
+
249
+ issues: list[ArtifactInferenceIssue] = []
250
+ inferred_format = _infer_format(location)
251
+ if artifact.format and inferred_format and artifact.format != inferred_format:
252
+ issues.append(
253
+ ArtifactInferenceIssue(
254
+ field="format",
255
+ declared_value=artifact.format,
256
+ inferred_value=inferred_format,
257
+ message=f"artifact {artifact.display_id} declares format {artifact.format!r}, but {inferred_format!r} was inferred from its location",
258
+ )
259
+ )
260
+
261
+ inferred_media_type = _infer_media_type(location)
262
+ if artifact.media_type and inferred_media_type and artifact.media_type != inferred_media_type:
263
+ issues.append(
264
+ ArtifactInferenceIssue(
265
+ field="media_type",
266
+ declared_value=artifact.media_type,
267
+ inferred_value=inferred_media_type,
268
+ message=(
269
+ f"artifact {artifact.display_id} declares media_type {artifact.media_type!r}, "
270
+ f"but {inferred_media_type!r} was inferred from its location"
271
+ ),
272
+ )
273
+ )
274
+
275
+ return tuple(issues)
276
+
277
+
278
+ def capability_from_value(value: Any) -> Capability:
279
+ if isinstance(value, Capability):
280
+ return value
281
+ if isinstance(value, str):
282
+ return Capability(name=value)
283
+ if isinstance(value, dict):
284
+ return Capability(**value)
285
+ return Capability.model_validate(value)
286
+
287
+
288
+ def has_capability(capabilities: tuple[CapabilityValue, ...], query: Any) -> bool:
289
+ if query is None or query == "":
290
+ return True
291
+ query_capability = capability_from_value(query)
292
+ return any(_capability_matches(capability_from_value(capability), query_capability) for capability in capabilities)
293
+
294
+
295
+ def _capability_matches(capability: Capability, query: Capability) -> bool:
296
+ return capability.name == query.name and (not query.kind or capability.kind == query.kind)
297
+
298
+
299
+ def _dump_capability(capability: Capability) -> str | dict[str, Any]:
300
+ if not capability.kind and not capability.metadata:
301
+ return capability.name
302
+ return capability.model_dump(mode="json", exclude_defaults=True)
artlink/cli.py ADDED
@@ -0,0 +1,85 @@
1
+ from __future__ import annotations
2
+
3
+ import argparse
4
+ import json
5
+ import sys
6
+ from collections.abc import Sequence
7
+ from pathlib import Path
8
+ from typing import TextIO
9
+
10
+ from .examples.domains.docs import DocumentationSiteScheme
11
+ from .examples.domains.hdl import HardwareProjectScheme
12
+ from .examples.domains.ml import ModelReleaseScheme
13
+ from .examples.domains.python import PythonPackageScheme
14
+ from .packages import build_package_archive, discover_packages, install_package_archive, normalize_package_type
15
+
16
+ __all__ = ("main",)
17
+
18
+
19
+ def main(argv: Sequence[str] | None = None, *, output_stream: TextIO | None = None) -> int:
20
+ parser = _parser()
21
+ args = parser.parse_args(list(argv) if argv is not None else None)
22
+ stream = output_stream or sys.stdout
23
+
24
+ if args.command == "package":
25
+ package_type = normalize_package_type(args.package_type)
26
+ scheme = _scheme_for_type(package_type)
27
+ manifest = scheme.bundle(root=Path(args.root), name=args.name, version=args.version)
28
+ archive_path = build_package_archive(manifest, artifact_root=Path(args.root), output_dir=Path(args.output_dir), package_type=package_type)
29
+ stream.write(f"{archive_path}\n")
30
+ return 0
31
+
32
+ if args.command == "install":
33
+ destination = install_package_archive(Path(args.archive), target_dir=Path(args.target_dir))
34
+ stream.write(f"{destination}\n")
35
+ return 0
36
+
37
+ if args.command == "registry":
38
+ packages = discover_packages(Path(args.root), package_type=args.package_type)
39
+ if args.format == "json":
40
+ stream.write(json.dumps([package.model_dump(mode="json") for package in packages], indent=2, sort_keys=True) + "\n")
41
+ else:
42
+ for package in packages:
43
+ stream.write(f"{package.package_type}\t{package.name}\t{package.version}\t{package.source}\n")
44
+ return 0
45
+
46
+ parser.error(f"unsupported command: {args.command}")
47
+ return 2
48
+
49
+
50
+ def _parser() -> argparse.ArgumentParser:
51
+ parser = argparse.ArgumentParser(description="Package, install, and discover artlink artifact packages.")
52
+ subparsers = parser.add_subparsers(dest="command", required=True)
53
+
54
+ package = subparsers.add_parser("package", help="bundle a project into a discoverable artlink tarball")
55
+ package.add_argument("--type", dest="package_type", required=True, help="package type, such as docs, HDL, ml, or python")
56
+ package.add_argument("--root", required=True, help="project root to scan")
57
+ package.add_argument("--name", required=True, help="package/manifest name")
58
+ package.add_argument("--version", required=True, help="package/manifest version")
59
+ package.add_argument("--output-dir", required=True, help="directory for the generated tarball")
60
+
61
+ install = subparsers.add_parser("install", help="extract a discoverable artlink tarball into an install root")
62
+ install.add_argument("archive", help="artlink tarball to install")
63
+ install.add_argument("--target-dir", required=True, help="install prefix to extract into")
64
+
65
+ registry = subparsers.add_parser("registry", help="list discoverable artlink packages")
66
+ registry.add_argument("--root", required=True, help="install prefix to search")
67
+ registry.add_argument("--type", dest="package_type", default="", help="optional package type filter, such as HDL")
68
+ registry.add_argument("--format", choices=("text", "json"), default="text")
69
+ return parser
70
+
71
+
72
+ def _scheme_for_type(package_type: str):
73
+ if package_type == "docs":
74
+ return DocumentationSiteScheme()
75
+ if package_type == "hdl":
76
+ return HardwareProjectScheme()
77
+ if package_type == "ml":
78
+ return ModelReleaseScheme()
79
+ if package_type == "python":
80
+ return PythonPackageScheme()
81
+ raise SystemExit(f"unsupported package type: {package_type}")
82
+
83
+
84
+ if __name__ == "__main__":
85
+ raise SystemExit(main())
artlink/cli_tools.py ADDED
@@ -0,0 +1,123 @@
1
+ from __future__ import annotations
2
+
3
+ import argparse
4
+ import json
5
+ import sys
6
+ from collections.abc import Sequence
7
+ from pathlib import Path
8
+ from typing import Any, Protocol, TextIO
9
+
10
+ from pydantic import ConfigDict
11
+
12
+ from .artifact import Reference, _ArtlinkModel
13
+ from .manifest import Manifest, load_manifest
14
+ from .registry import ArtifactRegistry
15
+ from .resolver import resolve_manifest
16
+
17
+ __all__ = (
18
+ "BundleScheme",
19
+ "InstallCollectScheme",
20
+ "SchemeCliCommand",
21
+ "build_packaging_parser",
22
+ "run_packaging_cli",
23
+ )
24
+
25
+
26
+ class BundleScheme(Protocol):
27
+ def bundle(self, *, root: Path, name: str, version: str = "", metadata: dict[str, Any] | None = None) -> Manifest: ...
28
+
29
+
30
+ class InstallCollectScheme(BundleScheme, Protocol):
31
+ def install_and_collect(self, resolution: Any, registry: ArtifactRegistry, *, target_dir: Path, path_method: str = "copy") -> Any: ...
32
+
33
+
34
+ class SchemeCliCommand(_ArtlinkModel):
35
+ model_config = ConfigDict(frozen=True, arbitrary_types_allowed=True)
36
+
37
+ name: str
38
+ scheme: Any
39
+ description: str = ""
40
+
41
+
42
+ def build_packaging_parser(commands: Sequence[SchemeCliCommand]) -> argparse.ArgumentParser:
43
+ parser = argparse.ArgumentParser(description="Build package-manager CLIs from artlink schemes.")
44
+ subparsers = parser.add_subparsers(dest="action", required=True)
45
+ _add_bundle_parser(subparsers, commands)
46
+ _add_install_parser(subparsers, commands)
47
+ return parser
48
+
49
+
50
+ def run_packaging_cli(
51
+ commands: Sequence[SchemeCliCommand],
52
+ argv: Sequence[str] | None = None,
53
+ *,
54
+ output_stream: TextIO | None = None,
55
+ ) -> int:
56
+ parser = build_packaging_parser(commands)
57
+ args = parser.parse_args(list(argv) if argv is not None else None)
58
+
59
+ command = _command_by_name(commands)[args.scheme]
60
+ if args.action == "bundle":
61
+ root = Path(args.root)
62
+ manifest = command.scheme.bundle(root=root, name=args.name, version=args.version, metadata={"artifact_root": root.as_posix()})
63
+ _write_text(args.output, manifest.to_yaml_text(), output_stream=output_stream)
64
+ return 0
65
+ if args.action == "install":
66
+ manifest_path = Path(args.manifest)
67
+ manifest = load_manifest(manifest_path)
68
+ registry = ArtifactRegistry.from_manifests((manifest,), root=_artifact_root(args.root, manifest, manifest_path))
69
+ request = Manifest(
70
+ name=f"{manifest.name}-request",
71
+ references=(Reference(kind="manifest", target=manifest.name, version=manifest.version),),
72
+ )
73
+ resolution = resolve_manifest(request, registry, provider_conflict_policy=args.provider_conflict_policy)
74
+ collection = command.scheme.install_and_collect(resolution, registry, target_dir=Path(args.target_dir), path_method=args.path_method)
75
+ if args.collection_output:
76
+ _write_text(
77
+ args.collection_output, json.dumps(collection.model_dump(mode="json"), indent=2, sort_keys=True) + "\n", output_stream=output_stream
78
+ )
79
+ return 0
80
+ parser.error(f"unsupported action: {args.action}")
81
+ return 2
82
+
83
+
84
+ def _add_bundle_parser(subparsers: Any, commands: Sequence[SchemeCliCommand]) -> None:
85
+ parser = subparsers.add_parser("bundle", help="bundle artifacts with a registered scheme")
86
+ parser.add_argument("scheme", choices=tuple(command.name for command in commands))
87
+ parser.add_argument("--root", required=True, help="project root to scan")
88
+ parser.add_argument("--name", required=True, help="manifest name")
89
+ parser.add_argument("--version", default="", help="manifest version")
90
+ parser.add_argument("--output", default="-", help="manifest output path, or '-' for stdout")
91
+
92
+
93
+ def _add_install_parser(subparsers: Any, commands: Sequence[SchemeCliCommand]) -> None:
94
+ parser = subparsers.add_parser("install", help="materialize and collect artifacts with a registered scheme")
95
+ parser.add_argument("scheme", choices=tuple(command.name for command in commands))
96
+ parser.add_argument("--manifest", required=True, help="manifest file to install")
97
+ parser.add_argument("--root", default="", help="artifact root; defaults to the manifest directory")
98
+ parser.add_argument("--target-dir", required=True, help="materialization target directory")
99
+ parser.add_argument("--path-method", choices=("copy", "symlink"), default="copy")
100
+ parser.add_argument("--provider-conflict-policy", choices=("error", "warning", "ignore", "prefer-explicit"), default="prefer-explicit")
101
+ parser.add_argument("--collection-output", default="", help="collection JSON output path")
102
+
103
+
104
+ def _command_by_name(commands: Sequence[SchemeCliCommand]) -> dict[str, SchemeCliCommand]:
105
+ return {command.name: command for command in commands}
106
+
107
+
108
+ def _write_text(path: str, text: str, *, output_stream: TextIO | None) -> None:
109
+ if path == "-":
110
+ (output_stream or sys.stdout).write(text)
111
+ return
112
+ output_path = Path(path)
113
+ output_path.parent.mkdir(parents=True, exist_ok=True)
114
+ output_path.write_text(text, encoding="utf-8")
115
+
116
+
117
+ def _artifact_root(root: str, manifest: Manifest, manifest_path: Path) -> Path:
118
+ if root:
119
+ return Path(root)
120
+ artifact_root = manifest.metadata.get("artifact_root")
121
+ if isinstance(artifact_root, str) and artifact_root:
122
+ return Path(artifact_root)
123
+ return manifest_path.parent
@@ -0,0 +1 @@
1
+ """Domain profiles built on top of artlink core models."""
@@ -0,0 +1,158 @@
1
+ from __future__ import annotations
2
+
3
+ import re
4
+ from collections.abc import Callable, Iterable
5
+ from pathlib import Path
6
+ from typing import Any
7
+
8
+ from pydantic import ConfigDict, Field, field_validator
9
+
10
+ from ..artifact import Artifact, Capability, _ArtlinkModel
11
+ from ..materialize import MaterializationPlan
12
+ from ..registry import ArtifactRegistry
13
+ from ..resolver import ResolutionPlan
14
+
15
+ __all__ = (
16
+ "ToolRequirement",
17
+ "artifact_id",
18
+ "first_path_for_role",
19
+ "matching_paths",
20
+ "path_artifacts",
21
+ "paths_for_role",
22
+ "resolved_artifact_locations",
23
+ "tool_artifact",
24
+ "tools_from_artifacts",
25
+ "unique_parent_dirs",
26
+ )
27
+
28
+ ProvidesFactory = Callable[[Path, Path], tuple[Capability, ...]]
29
+
30
+
31
+ class ToolRequirement(_ArtlinkModel):
32
+ model_config = ConfigDict(frozen=True)
33
+
34
+ name: str
35
+ version: str = "any"
36
+ packages: tuple[str, ...] = Field(default_factory=tuple)
37
+
38
+ @field_validator("name", "version")
39
+ @classmethod
40
+ def _validate_text(cls, value: str) -> str:
41
+ if not value:
42
+ raise ValueError("tool requirement fields must not be empty")
43
+ return value
44
+
45
+
46
+ def path_artifacts(
47
+ root: Path,
48
+ globs: tuple[str, ...],
49
+ *,
50
+ role: str,
51
+ kind: str,
52
+ language: str = "",
53
+ metadata: dict[str, Any] | None = None,
54
+ provides: ProvidesFactory | None = None,
55
+ ) -> tuple[Artifact, ...]:
56
+ artifacts: list[Artifact] = []
57
+ project_root = Path(root)
58
+ for path in matching_paths(project_root, globs):
59
+ relative_path = path.relative_to(project_root)
60
+ artifacts.append(
61
+ Artifact(
62
+ id=artifact_id(role, relative_path),
63
+ path=relative_path,
64
+ kind=kind,
65
+ role=role,
66
+ language=language,
67
+ provides=() if provides is None else provides(path, relative_path),
68
+ metadata=dict(metadata or {}),
69
+ )
70
+ )
71
+ return tuple(artifacts)
72
+
73
+
74
+ def tool_artifact(tool: ToolRequirement) -> Artifact:
75
+ metadata: dict[str, Any] = {"name": tool.name, "version": tool.version, "packages": list(tool.packages)}
76
+ provides = [Capability(kind="tool", name=tool.name)]
77
+ provides.extend(Capability(kind="python-package", name=package) for package in tool.packages)
78
+ return Artifact(
79
+ id=f"tool-{tool.name}",
80
+ uri=f"tool:{tool.name}",
81
+ kind="tool",
82
+ role="tool",
83
+ provides=tuple(provides),
84
+ metadata=metadata,
85
+ )
86
+
87
+
88
+ def matching_paths(root: Path, globs: tuple[str, ...]) -> tuple[Path, ...]:
89
+ seen: set[Path] = set()
90
+ paths: list[Path] = []
91
+ for pattern in globs:
92
+ for path in sorted(root.glob(pattern)):
93
+ if path.is_file() and path not in seen:
94
+ seen.add(path)
95
+ paths.append(path)
96
+ return tuple(paths)
97
+
98
+
99
+ def artifact_id(role: str, path: Path) -> str:
100
+ return f"{role}-{re.sub(r'[^A-Za-z0-9]+', '-', path.as_posix()).strip('-')}"
101
+
102
+
103
+ def resolved_artifact_locations(
104
+ resolution: ResolutionPlan,
105
+ registry: ArtifactRegistry,
106
+ *,
107
+ materialization_plan: MaterializationPlan | None,
108
+ ) -> Iterable[tuple[Artifact, Path | None]]:
109
+ resolved_manifest_keys = {_manifest_key(manifest.name, manifest.version) for manifest in resolution.resolved_manifests}
110
+ materialized_paths = {
111
+ (action.manifest_key, action.artifact_id): action.destination
112
+ for action in (() if materialization_plan is None else materialization_plan.actions)
113
+ if action.destination is not None
114
+ }
115
+ for entry in registry.artifacts():
116
+ manifest_key = _manifest_key(entry.manifest_name, entry.manifest_version)
117
+ if manifest_key not in resolved_manifest_keys:
118
+ continue
119
+ materialized_path = materialized_paths.get((manifest_key, entry.artifact.display_id))
120
+ if materialized_path is not None:
121
+ yield entry.artifact, materialized_path
122
+ elif entry.artifact.path is not None:
123
+ yield entry.artifact, registry.artifact_file_path(entry)
124
+ else:
125
+ yield entry.artifact, None
126
+
127
+
128
+ def paths_for_role(artifacts: tuple[tuple[Artifact, Path | None], ...], role: str) -> tuple[Path, ...]:
129
+ return tuple(sorted(path for artifact, path in artifacts if artifact.role == role and path is not None))
130
+
131
+
132
+ def first_path_for_role(artifacts: tuple[tuple[Artifact, Path | None], ...], role: str) -> Path | None:
133
+ paths = paths_for_role(artifacts, role)
134
+ if not paths:
135
+ return None
136
+ return paths[0]
137
+
138
+
139
+ def unique_parent_dirs(paths: tuple[Path, ...]) -> tuple[Path, ...]:
140
+ return tuple(sorted({path.parent for path in paths}))
141
+
142
+
143
+ def tools_from_artifacts(artifacts: tuple[tuple[Artifact, Path | None], ...]) -> dict[str, ToolRequirement]:
144
+ return {str(artifact.metadata["name"]): tool_requirement_from_artifact(artifact) for artifact, _ in artifacts if artifact.role == "tool"}
145
+
146
+
147
+ def tool_requirement_from_artifact(artifact: Artifact) -> ToolRequirement:
148
+ return ToolRequirement(
149
+ name=str(artifact.metadata["name"]),
150
+ version=str(artifact.metadata.get("version", "any")),
151
+ packages=tuple(str(package) for package in artifact.metadata.get("packages", ())),
152
+ )
153
+
154
+
155
+ def _manifest_key(name: str, version: str) -> str:
156
+ if version:
157
+ return f"{name}@{version}"
158
+ return name
@@ -0,0 +1 @@
1
+ """Runnable examples built on top of the reusable artlink core."""
@@ -0,0 +1 @@
1
+ """Example domain profiles for common artifact packaging workflows."""