Metadata-Version: 2.1
Name: shadwell
Version: 0.1
Summary: A package finder library for Python
Home-page: https://github.com/pfmoore/shadwell
Author: Paul Moore
Author-email: p.f.moore@gmail.com
Maintainer: Paul Moore
Maintainer-email: p.f.moore@gmail.com
License: MIT
Project-URL: Source, https://github.com/pfmoore/shadwell
Project-URL: Tracker, https://github.com/pfmoore/shadwell/issues
Description: # Shadwell - A finder for Python packages
        
        > It wasn't a dark and stormy night.<br/>
        > It should have been, but that's the weather for you.
        > 
        >  -- *"Good Omens", by Terry Pratchett and Neil Gaiman*
        
        Shadwell lets you find Python packages, from a set of "sources" (typically
        a package index or local directory).
        
        ## Finders
        In order to use the library, you need to create a `Finder` object, and then
        use that to fetch candidates for a requirement, as follows:
        
        ```python
        sources = [
            # A list of package sources, we'll come back to this
        ]
        finder = Finder(sources)
        results = finder.find(requirement)
        ```
        
        The results are returned in "best first" order, so callers which just want
        the best match can take the first result returned and ignore the rest.
        
        When creating a finder, you can supply any of the following arguments, to
        configure its behaviour:
        
        * `compatibility_tags`: This is a set of binary compatibility tags, used
          to determine if a wheel is compatible with the target platform. It should
          be a list of `packaging.tags.Tag` objects. Normally this will be omitted,
          in which case the default is to use `packaging.tags.sys_tags()`, which
          is the set supported by the current Python interpreter.
        * `allow_prerelease`: If this is `True`, the finder will return pre-release
          versions. Otherwise it will ignore prereleases (this is the default
          behaviour).
        * `python_version`: A `packaging.version.Version` object representing the
          target Python release. It is used to filter candidates based on their
          `Requires-Python` metadata. As usual, the current interpreter is used
          by default.
        * `wheel_policy`: This is a function that determines for a package, how
          we should choose between wheels and source distributions. Called with a
          package name, it should return one of the `WheelPolicy` values `ALLOW`
          (wheels can be used), `REQUIRE` (only wheels are allowed), `PROHIBIT`
          (wheels cannot be used, only sdists are allowed) or `PREFER` (older
          wheels will be selected in preference to newer source-only versions).
        * `allow_yanked`: This option only affects the case where all of the
          selected candidates are yanked. If there are any unyanked candidates,
          yanked candidates will be omitted regardless of the value of this option.
          If only yanked candidates are available, this option determines whether
          to return them rather than returning an empty list (the default).
          The intention here is to allow callers flexibility in how they implement
          the rules in [PEP 592](https://www.python.org/dev/peps/pep-0592/#installers).
        
        ## Candidates
        The objects returned from the finder are `Candidate` objects. The exact class
        is up to the source, but they must have the following attributes:
        
        * `name`: The project name (a string).
        * `version`: The project version (`packaging.version.Version`)
        * `requires_python`: The Python versions this candidate works with
          (`packaging.specifiers.SpecifierSet`)
        * `is_wheel`: Is this a wheel or sdist.
        * `tags`: The compatibility tags for this wheel (ignored for sdists).
          (`Set[packaging.tags.Tag]`)
        * `is_yanked`: Is this file yanked?
        
        ## Sources
        A `source` is any Python callable that takes a project name as an argument,
        and yields candidate objects for the named project. Note in particular that
        it is *not* the responsibility of the source to do any sort of filtering.
        
        ## Further possibilities
        
        1. Rather than having the finder return a flat list of candidates,
           maybe return a list of (version, ordered list of candidates)?
           That allows callers to more easily select the best candidate per
           version. However, "prefer wheel" may split the candidates for
           a version into 2 parts (wheels in one batch, sources in another),
           and that would be potentially *harder* for callers...
Keywords: packaging
Platform: any
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Utilities
Requires-Python: >=3.5
Description-Content-Type: text/markdown
Provides-Extra: test
