python.pypi
===========

.. py:module:: python.pypi


Attributes
----------

.. autoapisummary::

   python.pypi.logger


Classes
-------

.. autoapisummary::

   python.pypi.PyPIError
   python.pypi.PyPILink
   python.pypi.PyPILinksParser
   python.pypi.PyPI
   python.pypi.PyPICandidate
   python.pypi.PyPIProvider
   python.pypi.PyPIClosure


Functions
---------

.. autoapisummary::

   python.pypi.get_pip_env
   python.pypi.fetch_from_registry


Module Contents
---------------

.. py:data:: logger

.. py:class:: PyPIError

   Bases: :py:obj:`e3.error.E3Error`


.. py:function:: get_pip_env(platform: str, python_version: packaging.version.Version) -> dict[str, str]

   Return an environment used by pip to match requirements markers.

   :param platform: a platform (e3 format)
   :param python_version: the Python version to consider


.. py:class:: PyPILink(identifier: str, url: str, yanked: str | None, has_metadata: bool, require_python: str | None = None)

   Link returned by PyPI simple API.


   .. py:attribute:: identifier


   .. py:attribute:: url


   .. py:attribute:: yanked


   .. py:attribute:: require_python
      :value: None



   .. py:attribute:: has_metadata


   .. py:attribute:: _urlparse


   .. py:attribute:: checksum


   .. py:attribute:: filename


   .. py:attribute:: pkg_version


   .. py:attribute:: pkg_py_tags


   .. py:attribute:: pkg_abi_tags


   .. py:attribute:: pkg_platform_tags


   .. py:property:: is_yanked
      :type: bool


      Return True if the package is yanked.



   .. py:property:: metadata_url
      :type: str


      Return the metadata url.



   .. py:method:: as_dict() -> dict[str, None | bool | str]

      Serialize the a PyPILink into a Python dict that can be dump as json.



   .. py:method:: from_dict(data: dict) -> PyPILink
      :classmethod:


      Transform a generic dict into a PyPILink.

      :param data: the dict to read



.. py:class:: PyPILinksParser(identifier: str)

   Bases: :py:obj:`html.parser.HTMLParser`


   HTML parser to parse links from the PyPI simple API.


   .. py:attribute:: identifier


   .. py:attribute:: links
      :type:  list[PyPILink]
      :value: []



   .. py:method:: handle_starttag(tag: str, attrs: list[tuple[str, str | None]]) -> None

      See HTMLParser doc.



.. py:class:: PyPI(pypi_url: str = 'https://pypi.org/', allowed_yanked: list[str] | None = None, allowed_prerelease: list[str] | None = None, cache_dir: str = 'pypi.cache')

   .. py:attribute:: pypi_url
      :value: 'https://pypi.org/'



   .. py:attribute:: cache_dir
      :value: b'.'



   .. py:attribute:: cache
      :type:  dict[str, list[PyPILink]]


   .. py:attribute:: candidate_cache
      :type:  dict[str, list[PyPICandidate]]


   .. py:property:: pypi_cache_file
      :type: str


      Get location of file containing result of pypi requests.



   .. py:method:: fetch_project_links(name: str) -> list[PyPILink]

      Fetch list of resource for a given Python package.

      :param name: Python package name
      :return: a list of dict containing the link to each resource along with
          some metadata



   .. py:method:: fetch_candidates(identifier: str, env: dict[str, str], extras: set[str]) -> list[PyPICandidate]

      Return a list of candidates for a given package, env and list of extras.

      :param identifier: a normalized python package name or internal identifier
          computed by the provider
      :param env: the pip environment required
      :param extras: set of needed extras



   .. py:method:: save_cache() -> None

      Dump cache to disk.



   .. py:method:: load_cache() -> None

      Load cache from disk.



.. py:class:: PyPICandidate(identifier: str, link: PyPILink, extras: set[str], cache_dir: str)

   .. py:attribute:: name


   .. py:attribute:: url


   .. py:attribute:: is_yanked


   .. py:attribute:: has_direct_metadata


   .. py:attribute:: extras


   .. py:attribute:: cache_dir
      :value: b'.'



   .. py:attribute:: filename


   .. py:attribute:: version


   .. py:attribute:: py_tags


   .. py:attribute:: abi_tags


   .. py:attribute:: platform_tags


   .. py:attribute:: _reqs
      :type:  None | set[packaging.requirements.Requirement]
      :value: None



   .. py:property:: is_wheel
      :type: bool


      Check if resource is a wheel.



   .. py:method:: download() -> str

      Download the file in the PyPI cache.

      :return: the location of the file



   .. py:method:: requirements(env: dict[str, str]) -> set[packaging.requirements.Requirement]

      Return the list of requirements for the package.

      :param env: the environment used to evaluate requirements markers
      :return: a set of Requirement



   .. py:method:: is_compatible_with_platforms(platform_list: list[str]) -> bool

      Check if the package is compatible with a list of platform.

      :param platform_list: a list of platform name in e3 format (x86_64-linux, ...)
      :return: True if the package is compatible with any of the platform



   .. py:method:: is_compatible_with_cpython3(minor_version: int) -> bool

      Check whether the package is compatible with a given python 3 version.

      :param minor_version: to check compatibility with 3.10 set this param to 10
      :return: True if compatible



   .. py:property:: is_generic_wheel
      :type: bool


      Return whether the package is a generic package.

      If True then the wheel can be used on any Python 3.x version and on any
      platform.



   .. py:method:: __repr__() -> str


   .. py:method:: __str__() -> str


.. py:class:: PyPIProvider(env: dict[str, str], pypi: PyPI)

   Bases: :py:obj:`resolvelib.providers.AbstractProvider`


   Class that should declared to instanciate a resolver (see resolvelib doc).


   .. py:attribute:: pypi


   .. py:attribute:: env


   .. py:method:: identify(requirement_or_candidate: packaging.requirements.Requirement | PyPICandidate) -> str

      See resolvelib documentation.



   .. py:method:: get_preference(identifier: str, resolutions: collections.abc.Mapping[str, PyPICandidate], candidates: collections.abc.Mapping[str, collections.abc.Iterator[PyPICandidate]], information: collections.abc.Mapping[Any, collections.abc.Iterator[resolvelib.resolvers.RequirementInformation[Any, Any]]], backtrack_causes: collections.abc.Sequence[resolvelib.resolvers.RequirementInformation]) -> resolvelib.providers.Preference

      See resolvelib documentation.



   .. py:method:: find_matches(identifier: str, requirements: collections.abc.Mapping[str, collections.abc.Iterator[packaging.requirements.Requirement]], incompatibilities: collections.abc.Mapping[str, collections.abc.Iterator[PyPICandidate]]) -> resolvelib.structs.Matches

      Return the list of candidates that match a given list of requirements.



   .. py:method:: is_satisfied_by(requirement: packaging.requirements.Requirement, candidate: PyPICandidate) -> bool

      See resolvelib documentation.



   .. py:method:: get_dependencies(candidate: PyPICandidate) -> collections.abc.Iterable[packaging.requirements.Requirement]

      See resolvelib documentation.



.. py:class:: PyPIClosure(*, python3_version: str, platforms: list[str], cache_dir: str, pypi_url: str = 'https://pypi.org/', allowed_prerelease: list[str] | None = None, allowed_yanked: list[str] | None = None)

   Represent a closure of Python package from PyPI.


   .. py:attribute:: pypi


   .. py:attribute:: requirements
      :type:  set[packaging.requirements.Requirement]


   .. py:attribute:: allowed_prerelease
      :value: []



   .. py:attribute:: allowed_yanked
      :value: []



   .. py:attribute:: platforms


   .. py:attribute:: python3_version


   .. py:method:: add_wheel(filename: str) -> None

      Introduce a local wheel into the closure.



   .. py:method:: add_requirement(req: str | packaging.requirements.Requirement) -> None

      Add a requirement in the closure.



   .. py:method:: file_closure() -> list[str]


   .. py:method:: _requirements_closure() -> dict


   .. py:method:: requirements_closure() -> list[packaging.requirements.Requirement]

      Get the closure of requirements.

      :return: return a list of requirement that can be used as a lock file



   .. py:method:: __enter__() -> PyPIClosure


   .. py:method:: __exit__(_type: type[BaseException] | None, _val: BaseException | None, _tb: types.TracebackType | None) -> None


.. py:function:: fetch_from_registry(packages: collections.abc.Iterable[str], registry_url: str, *, log_missing_packages: bool = False) -> dict[str, PyPILink]

   Fetch packages currently in a registry.

   :param packages: The list of packages to look for.
   :param registry_url: The URL to a python registry to use.
       If the protocol is not defined on the URL, https will be used by default.
   :return: A filename to link mapping (dict).


