Fromager hooks and override plugins
===================================

For more complex customization requirements than are supported by the
configuration file, create an override plugin.

Plugins are registered using `entry
points <https://packaging.python.org/en/latest/specifications/entry-points/>`__
so they can be discovered and loaded at runtime. In `pyproject.toml`,
configure the entry point in the
``project.entry-points."fromager.project_overrides"`` namespace to
link the :ref:`canonical distribution name <canonical-distribution-names>`
to an importable module.

.. code-block:: toml
    :caption: pyproject.toml snippet

    [project.entry-points."fromager.project_overrides"]
    flit_core = "package_plugins.flit_core"
    pyarrow = "package_plugins.pyarrow"
    torch = "package_plugins.torch"
    triton = "package_plugins.triton"

The plugins are treated as providing overriding implementations of
functions with default implementations, so it is only necessary to
implement the functions needed to make it possible to build the
package.

Package settings hooks
----------------------

.. py:currentmodule:: fromager.packagesettings

.. autofromagerhook:: default_update_extra_environ

    The ``update_extra_environ`` can modify the extra environment variables
    from settings file with dynamic values. The hook must update the
    ``extra_environ`` dict in-place.

    The hook is called multiple times during a build. The ``version``
    argument is *None* for ``get_build_backend_dependencies`` and
    ``get_build_sdist_dependencies``. For ``get_install_dependencies_of_sdist``,
    ``build_sdist``, and ``build_wheel``, the ``version`` argument
    contains the resolved version.

    .. versionadded:: 0.60

Dependency hooks
----------------

.. py:currentmodule:: fromager.dependencies

.. autofromagerhook:: default_get_build_system_dependencies

    The ``get_build_system_dependencies()`` function should return the PEP 517
    build dependencies for a package.

    The arguments are the ``WorkContext``, the ``Requirement`` being evaluated,
    and the ``Path`` to the root of the source tree.

    The return value is an iterable of requirement specification strings for
    build system dependencies for the package. The caller is responsible for
    evaluating the requirements with the current build environment settings to
    determine if they are actually needed.

.. autofromagerhook:: default_get_build_backend_dependencies

    The ``get_build_backend_dependencies()`` function should return the PEP
    517 build dependencies for a package.

    The arguments are the ``WorkContext``, the ``Requirement`` being
    evaluated, and the `Path` to the root of the source tree.

    The return value is an iterable of requirement specification strings
    for build backend dependencies for the package. The caller is
    responsible for evaluating the requirements with the current build
    environment settings to determine if they are actually needed.

.. autofromagerhook:: default_get_build_sdist_dependencies

    The ``get_build_sdist_dependencies()`` function should return the PEP 517
    dependencies for building the source distribution for a package.

    The return value is an iterable of requirement specification strings
    for build backend dependencies for the package. The caller is
    responsible for evaluating the requirements with the current build
    environment settings to determine if they are actually needed.


Finder hooks
------------

.. py:currentmodule:: fromager.finders

.. autofromagerhook:: default_expected_source_archive_name

    The ``expected_source_archive_name()`` function is used to re-discover a
    source archive downloaded by a previous step, especially if the
    filename does not match the standard naming scheme for an sdist.

    The arguments are the ``Requirement`` being evaluated and the version to
    look for.

    The return value should be a string with the base filename (no paths)
    for the archive.

.. autofromagerhook:: default_expected_source_directory_name

    The ``expected_source_directory_name()`` function is used to re-discover
    the location of a source tree prepared by a previous step, especially
    if the name does not match the standard naming scheme for an sdist.

    The arguments are the ``Requirement`` being evaluated and the version to
    look for.

    The return value should be a string with the name of the source root
    directory relative to the ``ctx.work_dir`` where it was prepared.

Resolver hooks
--------------

.. currentmodule:: fromager.resolver

.. _resolver_provider_hook:

.. autofromagerhook:: default_resolver_provider

    The ``get_resolver_provider()`` function allows an override to change
    the way requirement specifications are converted to fixed
    versions. The default implementation looks for published versions on a
    Python package index. Most overrides do not need to implement this
    hook unless they are building versions of packages not released to
    https://pypi.org.

    For examples, refer to ``fromager.resolver.PyPIProvider``,
    ``fromager.resolver.GitHubTagProvider``, and ``fromager.resolver.GitLabTagProvider``.

    The arguments are the ``WorkContext``, the ``Requirement`` being
    evaluated, a boolean indicating whether source distributions should be
    included, a boolean indicating whether built wheels should be
    included, and the URL for the sdist server.

    The return value must be an instance of a class that implements the
    ``resolvelib.providers.AbstractProvider`` API.

    The expectation is that it acts as an engine for any sort of package resolution
    whether it is for wheels or sources. The provider can
    therefore use any value as the "URL" that will help it decide what to
    download. For example, the ``GitHubTagProvider`` returns the actual tag
    name in case that is different from the version number encoded within
    that tag name.

    The ``GenericProvider`` is a convenient base class, or can be instantiated
    directly if given a ``version_source`` callable that returns an iterator of
    version values as ``str`` or ``Version`` objects.

    .. code-block:: python

        from fromager import resolver

        VERSIONS = {
            "https://pkg.example/pkg-1.0.tar.gz": "1.0",
            "https://pkg.example/pkg-2.0.tar.gz": "2.0",
        }

        def _version_source(
                identifier: str,
            ) -> typing.Iterable[tuple[str, Version]]:
            return VERSIONS.items()


        def get_resolver_provider(ctx, req, include_sdists, include_wheels, sdist_server_url):
            return resolver.GenericProvider(version_source=_version_source, constraints=ctx.constraints)

    ``GenericProvider``, ``GitHubTagProvider``, and ``GitLabTagProvider`` take
    an optional ``matcher`` argument. The matcher can be a
    ``Callable[[str, str], Version | None]`` or a regular expression pattern
    object from ``re.compile``  The default match function attempts to convert
    a tag into a ``Version`` and ignores all errors.

    .. code-block:: python

       def custom_tag_match(identifier: str, item: str) -> Version | None:
           # project-1_2_3 -> 1.2.3
           if item.startswith("project-"):
               return Version(item[8:].replace("_", "."))
           # ignore other tags
           return None


Source hooks
------------

.. currentmodule:: fromager.sources

.. versionremoved:: 0.80.0
   The ``resolve_source`` hook and ``default_resolve_source`` function
   were removed. Define a :ref:`resolver_provider <resolver_provider_hook>` hook
   to resolve sources.

.. autofromagerhook:: default_download_source

    The ``download_source()`` function is responsible for downloading the
    source from a URL.

    The arguments are the ``WorkContext``, the ``Requirement`` being
    evaluated, version of the package being downloaded, the download URL,
    and the output directory in which the source should be downloaded.

    The return value should be a ``pathlib.Path`` file path to the downloaded source.

.. autofromagerhook:: default_prepare_source

    The ``prepare_source()`` function is responsible for setting up a tree
    of source files in a format that is ready to be built. The default
    implementation unpacks the source archive and applies patches.

    The arguments are the ``WorkContext``, the ``Requirement`` being
    evaluated, the ``Path`` to the source archive, and the version.

    The return value should be the ``Path`` to the root of the source tree,
    ideally inside the ``ctx.work_dir`` directory.

.. autofromagerhook:: default_build_sdist

    The ``build_sdist()`` function is responsible for creating a new source
    distribution from the prepared source tree and placing it in
    ``ctx.sdists_build``.  The dist name and version of the sdist file must
    match the ``Requirement`` and ``Version``.

    The arguments are the ``WorkContext``, the ``Requirement`` being evaluated, and the
    `Path` to the root of the source tree.

    The return value is the ``Path`` to the newly created source distribution.

Source helper functions
~~~~~~~~~~~~~~~~~~~~~~~

The following helper functions are available in the ``fromager.sources`` module
for use in custom source hooks:

.. autofunction:: fromager.sources.ensure_pkg_info

.. autofunction:: fromager.sources.pep517_build_sdist

.. autofunction:: fromager.sources.unpack_source

Wheel hooks
-----------

.. currentmodule:: fromager.wheels

.. autofromagerhook:: default_build_wheel

    The ``build_wheel()`` function is responsible for creating a wheel from
    the prepared source tree and placing it in ``ctx.wheels_build``. The
    default implementation uses :pep:`517` pyproject hook.  The dist name
    and version of the wheel must match the ``Requirement`` and ``Version``.

    The arguments are the ``WorkContext``, the ``Path`` to a virtualenv
    prepared with the build dependencies, a ``dict`` with extra environment
    variables to pass to the build, the ``Requirement`` being evaluated, and
    the ``Path`` to the root of the source tree.

    The return value is ignored.

.. autofromagerhook:: default_add_extra_metadata_to_wheels

    The ``add_extra_metadata_to_wheels()`` function is responsible to return any
    data the user would like to include in the wheels that fromager builds. This
    data will be added to the ``fromager-build-settings`` file under the
    ``.dist-info`` directory of the wheels. This file already contains the
    settings used to build that package.

    The arguments available are ``WorkContext``, ``Requirement`` being
    evaluated, the resolved ``Version`` of that requirement, a ``dict`` with extra
    environment variables, a ``Path`` to the root directory of the source
    distribution and a ``Path`` to the ``.dist-info`` directory of the wheel.

    The return value must be a ``dict``, otherwise it will be ignored.


Additional types
----------------

.. autoclass:: fromager.build_environment.BuildEnvironment
   :members: run

   .. autoproperty:: python

.. autoclass:: fromager.context.WorkContext

.. autoclass:: fromager.resolver.PyPIProvider

.. autoclass:: fromager.resolver.GenericProvider

.. autoclass:: fromager.resolver.GitHubTagProvider

.. autoclass:: fromager.resolver.GitLabTagProvider

.. autofunction:: fromager.sources.prepare_new_source