Distlib Documentation Release 0.3.4.dev0 Vinay Sajip Sep 22, 2021 Contents 1 Overview 3 1.1 Distlib evolved out of packaging ...................................3 1.2 What was the problem with packaging?...............................3 1.3 How Distlib can help...........................................4 1.4 How you can help............................................4 1.5 Main features...............................................4 1.6 Python version and platform compatibility...............................5 1.7 Project status...............................................5 1.8 Change log for distlib ........................................5 1.8.1 0.3.4 (future)..........................................5 1.8.2 0.3.3...............................................5 1.8.3 0.3.2...............................................6 1.8.4 0.3.1...............................................7 1.8.5 0.3.0...............................................7 1.8.6 0.2.9...............................................8 1.8.7 0.2.8...............................................8 1.8.8 0.2.7...............................................9 1.8.9 0.2.6...............................................9 1.8.10 0.2.5............................................... 10 1.8.11 0.2.4............................................... 10 1.8.12 0.2.3............................................... 11 1.8.13 0.2.2............................................... 11 1.8.14 0.2.1............................................... 12 1.8.15 0.2.0............................................... 12 1.8.16 0.1.9............................................... 13 1.8.17 0.1.8............................................... 14 1.8.18 0.1.7............................................... 15 1.8.19 0.1.6............................................... 15 1.8.20 0.1.5............................................... 15 1.8.21 0.1.4............................................... 16 1.8.22 0.1.3............................................... 16 1.8.23 0.1.2............................................... 17 1.8.24 0.1.1............................................... 18 1.8.25 0.1.0............................................... 19 1.9 Next steps................................................ 19 i 2 Tutorial 21 2.1 Installation................................................ 21 2.2 Testing.................................................. 21 2.2.1 PYPI availability........................................ 22 2.3 First steps................................................. 22 2.3.1 Using the database API..................................... 22 2.3.1.1 Distribution paths................................... 22 2.3.1.2 Querying a path for distributions........................... 23 2.3.1.3 Including legacy distributions in the search results.................. 23 2.3.1.4 Distribution properties................................. 24 2.3.1.5 Exporting things from Distributions.......................... 24 2.3.2 Distribution dependencies................................... 25 2.3.3 Using the locators API..................................... 25 2.3.3.1 Overview....................................... 25 2.3.3.2 Under the hood.................................... 26 2.3.4 Using the index API...................................... 27 2.3.4.1 Overview....................................... 27 2.3.4.2 Registering a project.................................. 27 2.3.4.3 Uploading a source distribution............................ 27 2.3.4.4 Uploading binary distributions............................ 28 2.3.4.5 Signing a distribution................................. 28 2.3.4.6 Downloading files................................... 28 2.3.4.7 Verifying signatures.................................. 29 2.3.4.8 Uploading documentation............................... 29 2.3.4.9 Authentication..................................... 29 2.3.4.10 Verifying HTTPS connections............................. 30 2.3.4.11 Saving a default configuration............................. 31 2.3.4.12 Searching PyPI.................................... 31 2.3.5 Using the metadata and markers APIs............................. 34 2.3.5.1 Instantiating metadata................................. 34 2.3.5.2 Reading metadata from files and streams....................... 34 2.3.5.3 Writing metadata to paths and streams........................ 35 2.3.5.4 Using markers..................................... 35 2.3.6 Using the resource API..................................... 35 2.3.6.1 Access to resources in the file system......................... 35 2.3.6.2 Access to resources in the .zip files......................... 36 2.3.6.3 Iterating over resources................................ 37 2.3.7 Using the scripts API...................................... 37 2.3.7.1 Specifying scripts to install.............................. 38 2.3.7.2 Wrapping callables with scripts............................ 38 2.3.7.3 Specifying a custom executable for shebangs..................... 39 2.3.7.4 Generating variants of a script............................. 40 2.3.7.5 Avoiding overwriting existing scripts......................... 40 2.3.7.6 Generating windowed scripts on Windows...................... 40 2.3.8 Using the version API..................................... 40 2.3.8.1 Overview....................................... 40 2.3.8.2 Matching versions against constraints......................... 41 2.3.9 Using the wheel API...................................... 42 2.3.9.1 Building wheels.................................... 42 2.3.9.2 Customising tags during build............................. 43 2.3.9.3 Specifying a wheel’s version............................. 43 2.3.9.4 Installing from wheels................................. 43 2.3.9.5 Verifying wheels.................................... 44 2.3.9.6 Modifying wheels................................... 44 ii 2.3.9.7 Mounting wheels................................... 45 2.3.9.8 Using vanilla pip to build wheels for existing distributions on PyPI......... 46 2.3.10 Using the manifest API..................................... 51 2.3.10.1 The include directive................................ 52 2.3.10.2 The exclude directive................................ 52 2.3.10.3 The global-include directive.......................... 52 2.3.10.4 The global-exclude directive.......................... 53 2.3.10.5 The recursive-include directive........................ 53 2.3.10.6 The recursive-exclude directive........................ 53 2.3.10.7 The graft directive................................. 53 2.3.10.8 The prune directive................................. 53 2.4 Next steps................................................ 53 3 Distlib’s design 55 3.1 The locators API........................................... 55 3.1.1 The problem we’re trying to solve............................... 55 3.1.2 A minimal solution....................................... 56 3.1.2.1 Locating distributions................................. 56 3.1.2.2 Finding dependencies................................. 57 3.2 The index API............................................. 58 3.2.1 The problem we’re trying to solve............................... 58 3.2.2 A minimal solution....................................... 58 3.3 The resources API.......................................... 59 3.3.1 The problem we’re trying to solve............................... 59 3.3.2 A minimal solution....................................... 60 3.3.3 Dealing with the requirement for access via file system files................. 62 3.4 The scripts API............................................ 63 3.4.1 The problem we’re trying to solve............................... 63 3.4.2 A minimal solution....................................... 63 3.4.2.1 Flag formats...................................... 64 3.5 The version API............................................ 65 3.5.1 The problem we’re trying to solve............................... 65 3.5.2 A minimal solution....................................... 66 3.5.2.1 Versions........................................ 66 3.5.2.2 Matchers........................................ 66 3.5.2.3 Version schemes.................................... 68 3.6 The wheel API............................................. 69 3.6.1 The problem we’re trying to solve............................... 69 3.6.2 A minimal solution....................................... 69 3.7 Next steps................................................ 70 4 API Reference 71 4.1 The distlib.database package.................................. 71 4.1.1 Classes............................................. 71 4.2 The distlib.resources package................................. 74 4.2.1 Attributes............................................ 74 4.2.2 Functions............................................ 75 4.2.3 Classes............................................. 75 4.3 The distlib.scripts package................................... 77 4.3.1 Classes............................................. 77 4.3.2 Functions............................................ 79 4.4 The distlib.locators package.................................. 79 4.4.1 Classes............................................. 79 4.4.2 Functions............................................ 82 iii 4.4.3 Variables............................................ 83 4.5 The distlib.index package..................................... 83 4.5.1 Classes............................................. 83 4.6 The distlib.util package..................................... 86 4.6.1 Classes............................................