@@ -219,6 +219,8 @@ Source hooks
219219 were removed. Define a :ref: `resolver_provider <resolver_provider_hook >` hook
220220 to resolve sources.
221221
222+ .. _download_source_hook :
223+
222224.. autofromagerhook :: default_download_source
223225
224226 The ``download_source() `` function is responsible for downloading the
@@ -228,7 +230,73 @@ Source hooks
228230 evaluated, version of the package being downloaded, the download URL,
229231 and the output directory in which the source should be downloaded.
230232
231- The return value should be a ``pathlib.Path `` file path to the downloaded source.
233+ For packages without ``source: `` configuration, return a ``pathlib.Path ``
234+ to the downloaded source. This legacy contract is unchanged.
235+
236+ .. versionchanged :: 0.96.0
237+
238+ The ``hook-sdist `` and ``hook-prebuilt `` source profiles accept
239+ :class: `~fromager.packagesettings.DownloadedSource ` with a local
240+ ``pathlib.Path `` and an explicit
241+ :class: `~fromager.packagesettings.DownloadKind `:
242+
243+ * ``hook-sdist `` accepts ``sdist ``, ``tarball ``, or ``git_checkout ``.
244+ * ``hook-prebuilt `` accepts only ``prebuilt_wheel ``.
245+
246+ A bare ``Path `` remains supported for legacy hooks: ``hook-sdist ``
247+ treats ``.tar.gz `` and ``.zip `` paths as ``sdist ``; ``hook-prebuilt ``
248+ treats ``.whl `` paths as ``prebuilt_wheel ``. Bare directories and other
249+ path forms are rejected. The sdist default preserves legacy archive
250+ semantics; it does not infer the artifact kind from archive contents.
251+ Hooks needing tarball or git-checkout semantics must return a typed
252+ result with the explicit kind. ``any_source `` and ``not_available ``
253+ are not valid concrete result kinds.
254+
255+ Invalid return types, malformed typed fields, and kinds incompatible
256+ with the profile raise errors identifying the package and hook.
257+ Hook exceptions are chained to a ``RuntimeError `` with that context;
258+ neither failures nor invalid results trigger a fallback download.
259+
260+ If the download hook is absent, ``hook-sdist `` downloads the candidate
261+ URL as an sdist into ``ctx.sdists_downloads ``. ``hook-prebuilt `` downloads
262+ it as a wheel into ``ctx.wheels_prebuilt ``. These defaults use the
263+ standard archive and wheel validation. Custom tarball URLs and git
264+ downloads require a download hook. The ``get_resolver_provider `` hook
265+ remains required for both profiles.
266+
267+ To migrate a raw-tarball hook to ``source: {provider: hook-sdist} ``, return
268+ its artifact kind explicitly:
269+
270+ .. code-block :: python
271+
272+ import pathlib
273+
274+ from packaging.requirements import Requirement
275+ from packaging.version import Version
276+
277+ from fromager import downloads
278+ from fromager.context import WorkContext
279+ from fromager.packagesettings import DownloadedSource, DownloadKind
280+
281+ def download_source (
282+ ctx : WorkContext,
283+ req : Requirement,
284+ version : Version,
285+ download_url : str ,
286+ sdists_downloads_dir : pathlib.Path,
287+ ) -> DownloadedSource:
288+ """ Download a raw source tarball and identify its kind."""
289+ path = downloads.download_url(
290+ destination_dir = sdists_downloads_dir,
291+ url = download_url,
292+ destination_filename = f " { req.name} - { version} .tar.gz " ,
293+ )
294+ return DownloadedSource(path = path, kind = DownloadKind.tarball)
295+
296+ A hook that clones sources returns the checkout directory with
297+ ``kind=DownloadKind.git_checkout ``. Typed results are supported through
298+ the configured hook profiles; packages using legacy settings still require
299+ a bare ``Path ``.
232300
233301.. autofromagerhook :: default_prepare_source
234302
0 commit comments