strawman api/docs changes for pyodide#175

CHANGELOG.md

@@ -6,6 +6,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
+### Added
+
+- Added support for constraining indirect dependencies via
+  `micropip.install(..., constraints=[...])`. and `micropip.set_constraints([...])`
+  [#xyz](https://github.com/pyodide/micropip/pull/xyz)
+
 ### Fixed
 
 - Fix a bug that prevented non-standard relative urls to be treated as such

docs/project/usage.md

@@ -71,18 +71,40 @@ You can pass multiple packages to `micropip.install`:
 await micropip.install(["pkg1", "pkg2"])
 ```
 
-You can specify additional constraints:
+A dependency can specify be refined per the [PEP-508] spec:
+
 
 ```python
 await micropip.install("snowballstemmer==2.2.0")
 await micropip.install("snowballstemmer>=2.2.0")
 await micropip.install("snowballstemmer[all]")
 ```
 
+[PEP-508]: https://peps.python.org/pep-0508
+
+### Disabling dependency resolution
+
 micropip does dependency resolution by default, but you can disable it,
 this is useful if you want to install a package that has a dependency
 which is not a pure Python package, but it is not mandatory for your use case:
 
 ```python
 await micropip.install("pkg", deps=False)
 ```
+
+### Constraining indirect dependencies
+
+Dependency resolution can be further customized with optional `constraints`: these
+provide the versions (or URLs of wheels)
+
+```python
+await micropip.install("pkg", constraints=["other-pkg ==0.1.1"])
+```
+
+Default `constraints` may be provided to be used by all subsequent calls to
+`micropip.install`:
+
+```python
+micropip.set_constraints = ["other-pkg ==0.1.1"]
+await micropip.install("pkg")
+```

micropip/install.py

@@ -20,6 +20,7 @@ async def install(
     credentials: str | None = None,
     pre: bool = False,
     *,
+    constraints: list[str] | None = None,
     verbose: bool | int | None = None,
 ) -> None:
     with setup_logging().ctx_level(verbose) as logger:
@@ -49,6 +50,7 @@ async def install(
             fetch_kwargs=fetch_kwargs,
             verbose=verbose,
             index_urls=index_urls,
+            constraints=constraints,
         )
         await transaction.gather_requirements(requirements)
 

micropip/package_manager.py

@@ -26,6 +26,7 @@ def __init__(self) -> None:
 
         self.repodata_packages: dict[str, dict[str, Any]] = REPODATA_PACKAGES
         self.repodata_info: dict[str, str] = REPODATA_INFO
+        self.constraints: list[str] = []
 
         pass
 
@@ -38,6 +39,7 @@ async def install(
         pre: bool = False,
         index_urls: list[str] | str | None = None,
         *,
+        constraints: list[str] | None = None,
         verbose: bool | int | None = None,
     ):
         """Install the given package and all of its dependencies.
@@ -122,6 +124,14 @@ async def install(
             - If a list of URLs is provided, micropip will try each URL in order until
             it finds a package. If no package is found, an error will be raised.
 
+        constraints :
+
+            A list of requirements with versions/URLs which will be used only if
+            needed by any ``requirements``.
+
+            Unlike ``requirements``, the package name _must_ be provided in the
+            PEP-508 format e.g. ``pkgname@https://...``.
+
         verbose :
             Print more information about the process. By default, micropip does not
             change logger level. Setting ``verbose=True`` will print similar
@@ -130,13 +140,17 @@ async def install(
         if index_urls is None:
             index_urls = self.index_urls
 
+        if constraints is None:
+            constraints = self.constraints
+
         return await install(
             requirements,
             index_urls,
             keep_going,
             deps,
             credentials,
             pre,
+            constraints=constraints,
             verbose=verbose,
         )
 

micropip/transaction.py

@@ -36,6 +36,7 @@ class Transaction:
     failed: list[Requirement] = field(default_factory=list)
 
     verbose: bool | int | None = None
+    constraints: list[str] | None = None
 
     def __post_init__(self):
         # If index_urls is None, pyodide-lock.json have to be searched first.