Add a public API

.github/workflows/publish.yml

@@ -2,12 +2,14 @@ name: Publish packages to PyPI
 
 on:
   create:
-    tags: "*"
+    tags:
+      - "[0-9]+.[0-9]+.[0-9]+"
+      - "[0-9]+.[0-9]+.[0-9]+[a-b][0-9]+"
+      - "[0-9]+.[0-9]+.[0-9]+rc[0-9]+"
 
 jobs:
   publish:
     runs-on: ubuntu-latest
-    if: startsWith(github.ref, 'refs/tags/')
     steps:
     - uses: actions/checkout@v3
     - name: Set up Python

.github/workflows/test.yml

@@ -35,19 +35,24 @@ jobs:
       uses: actions/setup-python@v4
       with:
         python-version: ${{ matrix.python-version }}
-    - uses: actions/cache@v3
-      with:
-        path: ~/.cache/pip
-        key: pip-test-${{ matrix.python-version }}-${{ matrix.os }}
-    - name: Install the project
-      run: "pip install --no-binary=:all: ."
-    - name: Install test dependencies
-      run: pip install .[test] coverage[toml]
+        cache: pip
+        cache-dependency-path: setup.cfg
+    - name: Install the project and its test dependencies
+      run: pip install --no-binary=setuptools,wheel .[test] coverage[toml]
     - name: Test with pytest
       run: |
-        coverage run -m pytest -W always
-        coverage xml
+        python -m coverage run -m pytest -W always
+        python -m coverage xml
     - name: Send coverage data to Codecov
       uses: codecov/codecov-action@v3
       with:
         file: coverage.xml
+
+  mypy:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - name: Install the project and its Mypy dependencies
+      run: pip install --no-binary=setuptools,wheel .[types]
+    - name: Test with Mypy
+      run: mypy

docs/news.rst

@@ -3,6 +3,8 @@ Release Notes
 
 **UNRELEASED**
 
+- Added a public API
+- Dropped support for converting ``bdist_wininst`` based installers into wheels
 - Updated vendored ``packaging`` to 22.0
 
 **0.38.4 (2022-11-09)**

docs/reference/wheel_convert.rst

@@ -12,14 +12,15 @@ Usage
 Description
 -----------
 
-Convert one or more eggs (``.egg``; made with ``bdist_egg``) or Windows
-installers (``.exe``; made with ``bdist_wininst``) into wheels.
+Convert one or more eggs (``.egg``; made with ``bdist_egg``) into wheels.
 
 Egg names must match the standard format:
 
 * ``<project>-<version>-pyX.Y`` for pure Python wheels
 * ``<project>-<version>-pyX.Y-<arch>`` for binary wheels
 
+Each argument can be either an ``.egg`` file, an unpacked egg directory or a directory
+containing eggs (packed or unpacked).
 
 Options
 -------

setup.cfg

@@ -39,11 +39,16 @@ where = src
 
 [options.extras_require]
 test =
-    pytest >= 3.0.0
+    pytest >= 6.2.0
+    setuptools >= 57
+types =
+    mypy >= 0.982
+    pytest >= 6.2
+    types-setuptools >= 65.5.0.2
 
 [options.entry_points]
 console_scripts =
-    wheel = wheel.cli:main
+    wheel = wheel._cli:main
 distutils.commands =
     bdist_wheel = wheel.bdist_wheel:bdist_wheel
 
@@ -57,10 +62,21 @@ max-line-length = 88
 
 [tool:pytest]
 testpaths = tests
+addopts = --tb=short
+filterwarnings =
+    ignore::DeprecationWarning:wheel.wheelfile
 
 [coverage:run]
 source = wheel
 omit = */vendored/*
 
 [coverage:report]
 show_missing = true
+
+[mypy]
+files = src,tests
+python_version = 3.8
+exclude = testdata/
+
+[mypy-wheel.vendored.*]
+ignore_errors = True

src/wheel/__init__.py

@@ -1,3 +1,18 @@
 from __future__ import annotations
 
-__version__ = "0.38.4"
+__all__ = [
+    "WheelError",
+    "WheelReader",
+    "WheelWriter",
+    "make_filename",
+    "write_wheelfile",
+]
+__version__ = "1.0.0a1"
+
+from ._wheelfile import (
+    WheelError,
+    WheelReader,
+    WheelWriter,
+    make_filename,
+    write_wheelfile,
+)

src/wheel/__main__.py

@@ -5,19 +5,20 @@
 from __future__ import annotations
 
 import sys
+from typing import NoReturn
 
 
-def main():  # needed for console script
+def main() -> NoReturn:  # needed for console script
     if __package__ == "":
         # To be able to run 'python wheel-0.9.whl/wheel':
         import os.path
 
         path = os.path.dirname(os.path.dirname(__file__))
         sys.path[0:0] = [path]
-    import wheel.cli
+    import wheel._cli
 
-    sys.exit(wheel.cli.main())
+    sys.exit(wheel._cli.main())
 
 
 if __name__ == "__main__":
-    sys.exit(main())
+    main()

src/wheel/cli/__init__.py → src/wheel/_cli/__init__.py

@@ -4,41 +4,41 @@
 
 from __future__ import annotations
 
-import argparse
 import os
 import sys
+from argparse import ArgumentParser, Namespace
 
 
 class WheelError(Exception):
     pass
 
 
-def unpack_f(args):
+def unpack_f(args: Namespace) -> None:
     from .unpack import unpack
 
     unpack(args.wheelfile, args.dest)
 
 
-def pack_f(args):
+def pack_f(args: Namespace) -> None:
     from .pack import pack
 
     pack(args.directory, args.dest_dir, args.build_number)
 
 
-def convert_f(args):
+def convert_f(args: Namespace) -> None:
     from .convert import convert
 
     convert(args.files, args.dest_dir, args.verbose)
 
 
-def version_f(args):
+def version_f(args: Namespace) -> None:
     from .. import __version__
 
-    print("wheel %s" % __version__)
+    print(f"wheel {__version__}")
 
 
-def parser():
-    p = argparse.ArgumentParser()
+def parser() -> ArgumentParser:
+    p = ArgumentParser()
     s = p.add_subparsers(help="commands")
 
     unpack_parser = s.add_parser("unpack", help="Unpack wheel")
@@ -61,8 +61,10 @@ def parser():
     )
     repack_parser.set_defaults(func=pack_f)
 
-    convert_parser = s.add_parser("convert", help="Convert egg or wininst to wheel")
-    convert_parser.add_argument("files", nargs="*", help="Files to convert")
+    convert_parser = s.add_parser("convert", help="Convert eggs to wheels")
+    convert_parser.add_argument(
+        "files", nargs="*", help=".egg files or directories to convert"
+    )
     convert_parser.add_argument(
         "--dest-dir",
         "-d",
@@ -81,7 +83,7 @@ def parser():
     return p
 
 
-def main():
+def main() -> int:
     p = parser()
     args = p.parse_args()
     if not hasattr(args, "func"):

src/wheel/_cli/convert.py

@@ -0,0 +1,126 @@
+from __future__ import annotations
+
+import os
+import re
+import zipfile
+from collections.abc import Generator, Iterable
+from email.message import Message
+from email.parser import HeaderParser
+from os import PathLike
+from pathlib import Path, PurePath
+from typing import IO, Any
+
+from .. import WheelWriter, make_filename
+from . import WheelError
+
+egg_info_re = re.compile(
+    r"""
+    (?P<name>.+?)-(?P<ver>.+?)
+    (-(?P<pyver>py\d\.\d+)
+     (-(?P<arch>.+?))?
+    )?.egg$""",
+    re.VERBOSE,
+)
+
+
+def egg2wheel(egg_path: Path, dest_dir: Path) -> None:
+    def egg_file_source() -> Generator[tuple[PurePath, IO[bytes]], Any, None]:
+        with zipfile.ZipFile(egg_path) as zf:
+            for zinfo in zf.infolist():
+                with zf.open(zinfo) as fp:
+                    yield PurePath(zinfo.filename), fp
+
+    def egg_dir_source() -> Generator[tuple[PurePath, IO[bytes]], Any, None]:
+        for root, _dirs, files in os.walk(egg_path, followlinks=False):
+            root_path = Path(root)
+            for fname in files:
+                file_path = root_path / fname
+                with file_path.open("rb") as fp:
+                    yield file_path, fp
+
+    match = egg_info_re.match(egg_path.name)
+    if not match:
+        raise WheelError(f"Invalid egg file name: {egg_path.name}")
+
+    # Assume pure Python if there is no specified architecture
+    # Assume all binary eggs are for CPython
+    egg_info = match.groupdict()
+    pyver = egg_info["pyver"].replace(".", "")
+    arch = (egg_info["arch"] or "any").replace(".", "_").replace("-", "_")
+    abi = "cp" + pyver[2:] if arch != "any" else "none"
+    root_is_purelib = arch is None
+
+    if egg_path.is_dir():
+        # buildout-style installed eggs directory
+        source = egg_dir_source()
+    else:
+        source = egg_file_source()
+
+    wheel_name = make_filename(
+        egg_info["name"], egg_info["ver"], impl_tag=pyver, abi_tag=abi, plat_tag=arch
+    )
+    metadata = Message()
+    with WheelWriter(
+        dest_dir / wheel_name, generator="egg2wheel", root_is_purelib=root_is_purelib
+    ) as wf:
+        for path, fp in source:
+            if path.parts[0] == "EGG-INFO":
+                if path.parts[1] == "requires.txt":
+                    requires = fp.read().decode("utf-8")
+                    extra = specifier = ""
+                    for line in requires.splitlines():
+                        line = line.strip()
+                        if line.startswith("[") and line.endswith("]"):
+                            extra, _, specifier = line[1:-1].strip().partition(":")
+                            metadata["Provides-Extra"] = extra
+                        elif line:
+                            specifiers: list[str] = []
+                            if extra:
+                                specifiers += f"extra == {extra!r}"
+
+                            if specifier:
+                                specifiers += specifier
+
+                            if specifiers:
+                                line = line + " ; " + " and ".join(specifiers)
+
+                            metadata["Requires-Dist"] = line
+                elif path.parts[1] in ("entry_points.txt", "top_level.txt"):
+                    wf.write_distinfo_file(path.parts[1], fp)
+                elif path.parts[1] == "PKG-INFO":
+                    pkg_info = HeaderParser().parsestr(fp.read().decode("utf-8"))
+                    pkg_info.replace_header("Metadata-Version", "2.1")
+                    del pkg_info["Provides-Extra"]
+                    del pkg_info["Requires-Dist"]
+                    for header, value in pkg_info.items():
+                        metadata[header] = value
+            else:
+                wf.write_file(path, fp)
+
+        if metadata:
+            wf.write_metadata(metadata.items())
+
+
+def convert(
+    files: Iterable[str | PathLike[str]], dest_dir: str | PathLike[str], verbose: bool
+) -> None:
+    dest_path = Path(dest_dir)
+    paths: list[Path] = []
+    for fname in files:
+        path = Path(fname)
+        if path.is_file():
+            paths.append(path)
+        elif path.is_dir():
+            paths.extend(path.iterdir())
+
+    for path in paths:
+        if path.suffix != ".egg":
+            continue
+
+        if verbose:
+            print(f"{path}... ", flush=True)
+
+        egg2wheel(path, dest_path)
+
+        if verbose:
+            print("OK")