path: root/assets/info/setuptools.info

This is setuptools.info, produced by makeinfo version 6.5 from
setuptools.texi.

     setuptools 50.3.2, Dec 04, 2020

     Python Packaging Authority

     Copyright © Python Packaging Authority

INFO-DIR-SECTION Miscellaneous
START-INFO-DIR-ENTRY
* setuptools: (setuptools.info). One line description of project
END-INFO-DIR-ENTRY


   Generated by Sphinx 2.3.1.


File: setuptools.info,  Node: Top,  Next: Building and Distributing Packages with Setuptools,  Up: (dir)

setuptools
**********

     setuptools 50.3.2, Dec 04, 2020

     Python Packaging Authority

     Copyright © Python Packaging Authority

Setuptools is a fully-featured, actively-maintained, and stable library
designed to facilitate packaging Python projects.

Documentation content:

* Menu:

* Building and Distributing Packages with Setuptools::
* Build System Support::
* Package Discovery and Resource Access using pkg_resources::
* Keywords::
* Roadmap::
* Building and Distributing Packages with Setuptools: Building and Distributing Packages with Setuptools<2>.
* Development on Setuptools::
* Guides on backward compatibility & deprecated practice::
* History: History<2>.
* Credits::
* Index::

 — The Detailed Node Listing —

Building and Distributing Packages with Setuptools

* Transition to PEP517::

Transition to PEP517

* setuptools Quickstart::
* Package Discovery and Namespace Package::
* Entry Points::
* Dependencies Management in Setuptools::
* Data Files Support::
* “Development Mode”::
* Tagging and “Daily Build” or “Snapshot” Releases::
* Generating Source Distributions::
* Distributing Extensions compiled with Cython::
* Specifying Your Project’s Version::
* Creating distutils Extensions::
* Configuring setup() using setup.cfg files: Configuring setup using setup cfg files.
* New and Changed setup() Keywords: New and Changed setup Keywords.
* Command Reference::
* Using setuptools to package and distribute your project::
* Automatic Resource Extraction::
* Defining Additional Metadata::
* Setting the zip_safe flag::

setuptools Quickstart

* Installation::
* Python packaging at a glance::
* Basic Use::
* Automatic package discovery::
* Entry points and automatic script creation::
* Dependency management::
* Including Data Files::
* Development mode::
* Uploading your package to PyPI::
* Transitioning from setup.py to setup.cfg: Transitioning from setup py to setup cfg.
* Resources on Python packaging::

Package Discovery and Namespace Package

* Using find; or find_packages: Using find or find_packages.
* Using find_namespace; or find_namespace_packages: Using find_namespace or find_namespace_packages.
* Legacy Namespace Packages::

Legacy Namespace Packages

* pkg_resource style namespace package::
* pkgutil style namespace package::

Entry Points

* Console Scripts::
* Advertising Behavior::
* Dependency Management::

Dependencies Management in Setuptools

* Build system requirement::
* Declaring required dependency::
* Optional dependencies::
* Python requirement::

Build system requirement

* Package requirement::

Declaring required dependency

* Platform specific dependencies::
* Dependencies that aren’t in PyPI::

Data Files Support

* Accessing Data Files at Runtime::
* Non-Package Data Files::

Generating Source Distributions

* Making “Official” (Non-Snapshot) Releases: Making “Official” Non-Snapshot Releases.

Creating distutils Extensions

* Adding Commands::
* Adding setup() Arguments: Adding setup Arguments.
* Customizing Distribution Options::
* Adding new EGG-INFO Files::
* Adding Support for Revision Control Systems::

Configuring setup() using setup.cfg files

* Using a src/ layout::
* Specifying values::

Specifying values

* Metadata::
* Options::

Command Reference

* alias - Define shortcuts for commonly used commands::
* bdist_egg - Create a Python Egg for the project::
* develop - Deploy the project source in “Development Mode”::
* egg_info - Create egg metadata and set build tags::
* rotate - Delete outdated distribution files::
* saveopts - Save used options to a configuration file::
* setopt - Set a distutils or setuptools option in a config file::
* test - Build package and run a unittest suite::
* upload - Upload source and/or egg distributions to PyPI::

egg_info - Create egg metadata and set build tags

* Release Tagging Options::
* Other egg_info Options::
* egg_info Examples::

saveopts - Save used options to a configuration file

* Configuration File Options::

Build System Support

* What is it?::
* How to use it?::

Package Discovery and Resource Access using pkg_resources

* Overview::
* API Reference::

API Reference

* Namespace Package Support::
* WorkingSet Objects::
* Environment Objects::
* Requirement Objects::
* Entry Points: Entry Points<2>.
* Distribution Objects::
* ResourceManager API::
* Metadata API::
* Exceptions::
* Supporting Custom Importers::
* Utility Functions::

WorkingSet Objects

* Basic WorkingSet Methods::
* WorkingSet Methods and Attributes::
* Receiving Change Notifications::
* Locating Plugins::

Requirement Objects

* Requirements Parsing::
* Requirement Methods and Attributes::

Entry Points

* Convenience API::
* Creating and Parsing::
* EntryPoint Objects::

Distribution Objects

* Getting or Creating Distributions::
* Distribution Attributes::
* Distribution Methods::

ResourceManager API

* Basic Resource Access::
* Resource Extraction::
* “Provider” Interface::

Metadata API

* IMetadataProvider Methods::

Supporting Custom Importers

* IResourceProvider::
* Built-in Resource Providers::

Utility Functions

* Parsing Utilities::
* Platform Utilities::
* PEP 302 Utilities::
* File/Path Utilities::
* History::

Building and Distributing Packages with Setuptools

* Developer’s Guide::

Developer’s Guide

* TRANSITIONAL NOTE::

TRANSITIONAL NOTE

* setup.cfg-only projects: setup cfg-only projects.
* Configuration API::
* Mailing List and Bug Tracker::

Development on Setuptools

* Developer’s Guide for Setuptools::
* Release Process::

Developer’s Guide for Setuptools

* Recommended Reading::
* Project Management::
* Authoring Tickets::
* Making a pull request::
* Auto-Merge Requests::
* Testing::
* Semantic Versioning::
* Building Documentation::
* Vendored Dependencies::

Making a pull request

* Adding change notes with your PRs::
* Alright! So how to add a news fragment?::
* Examples for adding changelog entries to your Pull Requests::

Release Process

* Release Frequency::
* Release Managers::

Guides on backward compatibility & deprecated practice

* Supporting both Python 2 and Python 3 with Setuptools::
* The Internal Structure of Python Eggs::
* Easy Install::
* Porting from Distutils::
* “Eggsecutable” Scripts::

Supporting both Python 2 and Python 3 with Setuptools

* Using 2to3::
* Distributing Python 3 modules::
* Advanced features::

Using 2to3

* Differential conversion::

The Internal Structure of Python Eggs

* Eggs and their Formats::
* Standard Metadata::
* Other Technical Considerations::

Eggs and their Formats

* Code and Resources::
* Project Metadata::
* Filename-Embedded Metadata::
* Egg Links::

Standard Metadata

* .txt File Formats: txt File Formats.
* Dependency Metadata::
* namespace_packages.txt – Namespace Package Metadata: namespace_packages txt – Namespace Package Metadata.
* entry_points.txt – “Entry Point”/Plugin Metadata: entry_points txt – “Entry Point”/Plugin Metadata.
* The scripts Subdirectory::
* Zip Support Metadata::
* top_level.txt – Conflict Management Metadata: top_level txt – Conflict Management Metadata.
* SOURCES.txt – Source Files Manifest: SOURCES txt – Source Files Manifest.

Dependency Metadata

* requires.txt: requires txt.
* setup_requires.txt: setup_requires txt.
* dependency_links.txt: dependency_links txt.
* depends.txt – Obsolete, do not create!: depends txt – Obsolete do not create!.

Zip Support Metadata

* native_libs.txt: native_libs txt.
* eager_resources.txt: eager_resources txt.
* zip-safe and not-zip-safe::

Other Technical Considerations

* Zip File Issues::
* Installation and Path Management Issues::

Zip File Issues

* The Extraction Process::
* Extension Import Wrappers::

Installation and Path Management Issues

* Script Wrappers::

Easy Install

* Using “Easy Install”::
* Reference Manual::

Using “Easy Install”

* Installing “Easy Install”::
* Downloading and Installing a Package::
* Upgrading a Package::
* Changing the Active Version::
* Uninstalling Packages::
* Managing Scripts::
* Executables and Launchers::
* Tips & Techniques::
* Password-Protected Sites::
* Using .pypirc Credentials: Using pypirc Credentials.

Installing “Easy Install”

* Troubleshooting::
* Windows Notes::

Executables and Launchers

* Windows Executable Launcher::
* Natural Script Launcher::

Tips & Techniques

* Multiple Python Versions::
* Restricting Downloads with --allow-hosts::
* Installing on Un-networked Machines::
* Packaging Others’ Projects As Eggs::
* Creating your own Package Index::

Using .pypirc Credentials

* Controlling Build Options::
* Editing and Viewing Source Packages::
* Dealing with Installation Conflicts::
* Compressed Installation::

Reference Manual

* Configuration Files::
* Command-Line Options::
* Custom Installation Locations::
* Package Index “API”::

Custom Installation Locations

* Use the “–user” option::
* Use the “–user” option and customize “PYTHONUSERBASE”::
* Use “virtualenv”::

Porting from Distutils

* Prefer Setuptools::

History

* v50.3.2: v50 3 2.
* v50.3.1: v50 3 1.
* v50.3.0: v50 3 0.
* v50.2.0: v50 2 0.
* v50.1.0: v50 1 0.
* v50.0.3: v50 0 3.
* v50.0.2: v50 0 2.
* v50.0.1: v50 0 1.
* v50.0.0: v50 0 0.
* v49.6.0: v49 6 0.
* v49.5.0: v49 5 0.
* v49.4.0: v49 4 0.
* v49.3.2: v49 3 2.
* v49.3.1: v49 3 1.
* v49.3.0: v49 3 0.
* v49.2.1: v49 2 1.
* v49.2.0: v49 2 0.
* v49.1.3: v49 1 3.
* v49.1.2: v49 1 2.
* v49.1.1: v49 1 1.
* v49.0.1: v49 0 1.
* v49.1.0: v49 1 0.
* v49.0.0: v49 0 0.
* v48.0.0: v48 0 0.
* v47.3.2: v47 3 2.
* v47.3.1: v47 3 1.
* v47.3.0: v47 3 0.
* v47.2.0: v47 2 0.
* v47.1.1: v47 1 1.
* v44.1.1: v44 1 1.
* v47.1.0: v47 1 0.
* v47.0.0: v47 0 0.
* v46.4.0: v46 4 0.
* v46.3.1: v46 3 1.
* v46.3.0: v46 3 0.
* v46.2.0: v46 2 0.
* v46.1.3: v46 1 3.
* v46.1.2: v46 1 2.
* v46.1.1: v46 1 1.
* v46.1.0: v46 1 0.
* v44.1.0: v44 1 0.
* v46.0.0: v46 0 0.
* v45.3.0: v45 3 0.
* v45.2.0: v45 2 0.
* v45.1.0: v45 1 0.
* v45.0.0: v45 0 0.
* v44.0.0: v44 0 0.
* v43.0.0: v43 0 0.
* v42.0.2: v42 0 2.
* v42.0.1: v42 0 1.
* v42.0.0: v42 0 0.
* v41.6.0: v41 6 0.
* v41.5.1: v41 5 1.
* v41.5.0: v41 5 0.
* v41.4.0: v41 4 0.
* v41.3.0: v41 3 0.
* v41.2.0: v41 2 0.
* v41.1.0: v41 1 0.
* v41.0.1: v41 0 1.
* v41.0.0: v41 0 0.
* v40.9.0: v40 9 0.
* v40.8.0: v40 8 0.
* v40.7.3: v40 7 3.
* v40.7.2: v40 7 2.
* v40.7.1: v40 7 1.
* v40.7.0: v40 7 0.
* v40.6.3: v40 6 3.
* v40.6.2: v40 6 2.
* v40.6.1: v40 6 1.
* v40.6.0: v40 6 0.
* v40.5.0: v40 5 0.
* v40.4.3: v40 4 3.
* v40.4.2: v40 4 2.
* v40.4.1: v40 4 1.
* v40.4.0: v40 4 0.
* v40.3.0: v40 3 0.
* v40.2.0: v40 2 0.
* v40.1.1: v40 1 1.
* v40.1.0: v40 1 0.
* v40.0.0: v40 0 0.
* v39.2.0: v39 2 0.
* v39.1.0: v39 1 0.
* v39.0.1: v39 0 1.
* v39.0.0: v39 0 0.
* v38.7.0: v38 7 0.
* v38.6.1: v38 6 1.
* v38.6.0: v38 6 0.
* v38.5.2: v38 5 2.
* v38.5.1: v38 5 1.
* v38.5.0: v38 5 0.
* v38.4.1: v38 4 1.
* v38.4.0: v38 4 0.
* v38.3.0: v38 3 0.
* v38.2.5: v38 2 5.
* v38.2.4: v38 2 4.
* v38.2.3: v38 2 3.
* v38.2.2: v38 2 2.
* v38.2.1: v38 2 1.
* v38.2.0: v38 2 0.
* v38.1.0: v38 1 0.
* v38.0.0: v38 0 0.
* v37.0.0: v37 0 0.
* v36.8.0: v36 8 0.
* v36.7.3: v36 7 3.
* v36.7.2: v36 7 2.
* v36.7.1: v36 7 1.
* v36.7.0: v36 7 0.
* v36.6.1: v36 6 1.
* v36.6.0: v36 6 0.
* v36.5.0: v36 5 0.
* v36.4.0: v36 4 0.
* v36.3.0: v36 3 0.
* v36.2.7: v36 2 7.
* v36.2.6: v36 2 6.
* v36.2.5: v36 2 5.
* v36.2.4: v36 2 4.
* v36.2.3: v36 2 3.
* v36.2.2: v36 2 2.
* v36.2.1: v36 2 1.
* v36.2.0: v36 2 0.
* v36.1.1: v36 1 1.
* v36.1.0: v36 1 0.
* v36.0.1: v36 0 1.
* v36.0.0: v36 0 0.
* v35.0.2: v35 0 2.
* v35.0.1: v35 0 1.
* v35.0.0: v35 0 0.
* v34.4.1: v34 4 1.
* v34.4.0: v34 4 0.
* v34.3.3: v34 3 3.
* v34.3.2: v34 3 2.
* v34.3.1: v34 3 1.
* v34.3.0: v34 3 0.
* v34.2.0: v34 2 0.
* v34.1.1: v34 1 1.
* v34.1.0: v34 1 0.
* v34.0.3: v34 0 3.
* v34.0.2: v34 0 2.
* v34.0.1: v34 0 1.
* v34.0.0: v34 0 0.
* v33.1.1: v33 1 1.
* v33.1.0: v33 1 0.
* v33.0.0: v33 0 0.
* v32.3.1: v32 3 1.
* v32.3.0: v32 3 0.
* v32.2.0: v32 2 0.
* v32.1.3: v32 1 3.
* v32.1.2: v32 1 2.
* v32.1.1: v32 1 1.
* v32.1.0: v32 1 0.
* v32.0.0: v32 0 0.
* v31.0.1: v31 0 1.
* v31.0.0: v31 0 0.
* v30.4.0: v30 4 0.
* v30.3.0: v30 3 0.
* v30.2.1: v30 2 1.
* v30.2.0: v30 2 0.
* v30.1.0: v30 1 0.
* v30.0.0: v30 0 0.
* v29.0.1: v29 0 1.
* v29.0.0: v29 0 0.
* v28.8.0: v28 8 0.
* v28.7.1: v28 7 1.
* v28.7.0: v28 7 0.
* v28.6.1: v28 6 1.
* v28.6.0: v28 6 0.
* v28.5.0: v28 5 0.
* v28.4.0: v28 4 0.
* v28.3.0: v28 3 0.
* v28.1.0: v28 1 0.
* v28.0.0: v28 0 0.
* v27.3.1: v27 3 1.
* v27.3.0: v27 3 0.
* v27.2.0: v27 2 0.
* v27.1.2: v27 1 2.
* v27.1.1: v27 1 1.
* v27.1.0: v27 1 0.
* v27.0.0: v27 0 0.
* v26.1.1: v26 1 1.
* v26.1.0: v26 1 0.
* v26.0.0: v26 0 0.
* v25.4.0: v25 4 0.
* v25.3.0: v25 3 0.
* v25.2.0: v25 2 0.
* v25.1.6: v25 1 6.
* v25.1.5: v25 1 5.
* v25.1.4: v25 1 4.
* v25.1.3: v25 1 3.
* v25.1.2: v25 1 2.
* v25.1.1: v25 1 1.
* v25.1.0: v25 1 0.
* v25.0.2: v25 0 2.
* v25.0.1: v25 0 1.
* v25.0.0: v25 0 0.
* v24.3.1: v24 3 1.
* v24.3.0: v24 3 0.
* v24.2.1: v24 2 1.
* v24.2.0: v24 2 0.
* v24.1.1: v24 1 1.
* v24.1.0: v24 1 0.
* v24.0.3: v24 0 3.
* v24.0.2: v24 0 2.
* v24.0.1: v24 0 1.
* v24.0.0: v24 0 0.
* v23.2.1: v23 2 1.
* v23.1.0: v23 1 0.
* v23.0.0: v23 0 0.
* v22.0.5: v22 0 5.
* v22.0.4: v22 0 4.
* v22.0.3: v22 0 3.
* v22.0.2: v22 0 2.
* v22.0.1: v22 0 1.
* v22.0.0: v22 0 0.
* v21.2.2: v21 2 2.
* v21.2.1: v21 2 1.
* v21.2.0: v21 2 0.
* v21.1.0: v21 1 0.
* v21.0.0: v21 0 0.
* v20.10.0: v20 10 0.
* v20.9.0: v20 9 0.
* v20.8.1: v20 8 1.
* v20.8.0: v20 8 0.
* v20.7.0: v20 7 0.
* v20.6.8: v20 6 8.
* v20.6.7: v20 6 7.
* v20.6.6: v20 6 6.
* v20.6.0: v20 6 0.
* 20.5: 20 5.
* 20.4: 20 4.
* 20.3.1: 20 3 1.
* 20.3: 20 3.
* 20.2.2: 20 2 2.
* 20.2.1: 20 2 1.
* 20.2: 20 2.
* 20.1.1: 20 1 1.
* 20.1: 20 1.
* 20.0: 20 0.
* 19.7: 19 7.
* 19.6.2: 19 6 2.
* 19.6.1: 19 6 1.
* 19.6: 19 6.
* 19.5: 19 5.
* 19.4.1: 19 4 1.
* 19.4: 19 4.
* 19.3: 19 3.
* 19.2: 19 2.
* 19.1.1: 19 1 1.
* 19.1: 19 1.
* 19.0: 19 0.
* 18.8.1: 18 8 1.
* 18.8: 18 8.
* 18.7.1: 18 7 1.
* 18.7: 18 7.
* 18.6.1: 18 6 1.
* 18.6: 18 6.
* 18.5: 18 5.
* 18.4: 18 4.
* 18.3.2: 18 3 2.
* 18.3.1: 18 3 1.
* 18.3: 18 3.
* 18.2: 18 2.
* 18.1: 18 1.
* 18.0.1: 18 0 1.
* 18.0: 18 0.
* 17.1.1: 17 1 1.
* 17.1: 17 1.
* 17.0: 17 0.
* 16.0: 16 0.
* 15.2: 15 2.
* 15.1: 15 1.
* 15.0: 15 0.
* 14.3.1: 14 3 1.
* 14.3: 14 3.
* 14.2: 14 2.
* 14.1.1: 14 1 1.
* 14.1: 14 1.
* 14.0: 14 0.
* 13.0.2: 13 0 2.
* 13.0.1: 13 0 1.
* 13.0: 13 0.
* 12.4: 12 4.
* 12.3: 12 3.
* 12.2: 12 2.
* 12.1: 12 1.
* 12.0.5: 12 0 5.
* 12.0.4: 12 0 4.
* 12.0.3: 12 0 3.
* 12.0.2: 12 0 2.
* 12.0.1: 12 0 1.
* 12.0: 12 0.
* 11.3.1: 11 3 1.
* 11.3: 11 3.
* 11.2: 11 2.
* 11.1: 11 1.
* 11.0: 11 0.
* 10.2.1: 10 2 1.
* 10.2: 10 2.
* 10.1: 10 1.
* 10.0.1: 10 0 1.
* 10.0: 10 0.
* 9.1: 9 1.
* 9.0.1: 9 0 1.
* 9.0: 9 0.
* 8.4: 8 4.
* 8.3: 8 3.
* 8.2.1: 8 2 1.
* 8.2: 8 2.
* 8.1: 8 1.
* 8.0.4: 8 0 4.
* 8.0.3: 8 0 3.
* 8.0.2: 8 0 2.
* 8.0.1: 8 0 1.
* 8.0: 8 0.
* 7.0: 7 0.
* 6.1: 6 1.
* 6.0.2: 6 0 2.
* 6.0.1: 6 0 1.
* 6.0: 6 0.
* 5.8: 5 8.
* 5.7: 5 7.
* 5.6: 5 6.
* 5.5.1: 5 5 1.
* 5.5: 5 5.
* 5.4.2: 5 4 2.
* 5.4.1: 5 4 1.
* 5.4: 5 4.
* 5.3: 5 3.
* 5.2: 5 2.
* 5.1: 5 1.
* 5.0.2: 5 0 2.
* 5.0.1: 5 0 1.
* 5.0: 5 0.
* 3.7.1 and 3.8.1 and 4.0.1: 3 7 1 and 3 8 1 and 4 0 1.
* 4.0: 4 0.
* 3.8: 3 8.
* 3.7: 3 7.
* 3.6: 3 6.
* 3.5.2: 3 5 2.
* 3.5.1: 3 5 1.
* 3.5: 3 5.
* 3.4.4: 3 4 4.
* 3.4.3: 3 4 3.
* 3.4.2: 3 4 2.
* 3.4.1: 3 4 1.
* 3.4: 3 4.
* 3.3: 3 3.
* 3.2: 3 2.
* 3.1: 3 1.
* 3.0.2: 3 0 2.
* 3.0.1: 3 0 1.
* 3.0: 3 0.
* 2.2: 2 2.
* 2.1.2: 2 1 2.
* 2.1.1: 2 1 1.
* 2.1: 2 1.
* 2.0.2: 2 0 2.
* 2.0.1: 2 0 1.
* 2.0: 2 0.
* 1.4.2: 1 4 2.
* 1.4.1: 1 4 1.
* 1.4: 1 4.
* 1.3.2: 1 3 2.
* 1.3.1: 1 3 1.
* 1.3: 1 3.
* 1.2: 1 2.
* 1.1.7: 1 1 7.
* 1.1.6: 1 1 6.
* 1.1.5: 1 1 5.
* 1.1.4: 1 1 4.
* 1.1.3: 1 1 3.
* 1.1.2: 1 1 2.
* 1.1.1: 1 1 1.
* 1.1: 1 1.
* 1.0: 1 0.
* 0.9.8: 0 9 8.
* 0.9.7: 0 9 7.
* 0.9.6: 0 9 6.
* 0.9.5: 0 9 5.
* 0.9.4: 0 9 4.
* 0.9.3: 0 9 3.
* 0.9.2: 0 9 2.
* 0.9.1: 0 9 1.
* 0.9: 0 9.
* 0.8: 0 8.
* 0.7.8: 0 7 8.
* 0.7.7: 0 7 7.
* 0.7.6: 0 7 6.
* 0.7.5: 0 7 5.
* 0.7.4: 0 7 4.
* 0.7.3: 0 7 3.
* 0.7.2: 0 7 2.
* 0.7.1: 0 7 1.
* 0.7: 0 7.
* 0.7b4: 0 7b4.
* 0.6.49: 0 6 49.
* 0.6.48: 0 6 48.
* 0.6.47: 0 6 47.
* 0.6.46: 0 6 46.
* 0.6.45: 0 6 45.
* 0.6.44: 0 6 44.
* 0.6.43: 0 6 43.
* 0.6.42: 0 6 42.
* 0.6.41: 0 6 41.
* 0.6.40: 0 6 40.
* 0.6.39: 0 6 39.
* 0.6.38: 0 6 38.
* 0.6.37: 0 6 37.
* 0.6.36: 0 6 36.
* 0.6.35: 0 6 35.
* 0.6.34: 0 6 34.
* 0.6.33: 0 6 33.
* 0.6.32: 0 6 32.
* 0.6.31: 0 6 31.
* 0.6.30: 0 6 30.
* 0.6.29: 0 6 29.
* 0.6.28: 0 6 28.
* 0.6.27: 0 6 27.
* 0.6.26: 0 6 26.
* 0.6.25: 0 6 25.
* 0.6.24: 0 6 24.
* 0.6.23: 0 6 23.
* 0.6.21: 0 6 21.
* 0.6.20: 0 6 20.
* 0.6.19: 0 6 19.
* 0.6.18: 0 6 18.
* 0.6.17: 0 6 17.
* 0.6.16: 0 6 16.
* 0.6.15: 0 6 15.
* 0.6.14: 0 6 14.
* 0.6.13: 0 6 13.
* 0.6.12: 0 6 12.
* 0.6.11: 0 6 11.
* 0.6.10: 0 6 10.
* 0.6.9: 0 6 9.
* 0.6.8: 0 6 8.
* 0.6.7: 0 6 7.
* 0.6.6: 0 6 6.
* 0.6.5: 0 6 5.
* 0.6.4: 0 6 4.
* 0.6.3: 0 6 3.
* 0.6.2: 0 6 2.
* 0.6.1: 0 6 1.
* 0.6: 0 6.
* 0.6c9: 0 6c9.
* 0.6c7: 0 6c7.
* 0.6c6: 0 6c6.
* 0.6c5: 0 6c5.
* 0.6c4: 0 6c4.
* 0.6c3: 0 6c3.
* 0.6c2: 0 6c2.
* 0.6c1: 0 6c1.
* 0.6b4: 0 6b4.
* 0.6b3: 0 6b3.
* 0.6b2: 0 6b2.
* 0.6b1: 0 6b1.
* 0.6a11: 0 6a11.
* 0.6a10: 0 6a10.
* 0.6a9: 0 6a9.
* 0.6a8: 0 6a8.
* 0.6a7: 0 6a7.
* 0.6a6: 0 6a6.
* 0.6a5: 0 6a5.
* 0.6a3: 0 6a3.
* 0.6a2: 0 6a2.
* 0.6a1: 0 6a1.
* 0.5a12: 0 5a12.
* 0.5a11: 0 5a11.
* 0.5a10: 0 5a10.
* 0.5a9: 0 5a9.
* 0.5a8: 0 5a8.
* 0.5a7: 0 5a7.
* 0.5a6: 0 5a6.
* 0.5a5: 0 5a5.
* 0.5a4: 0 5a4.
* 0.5a3: 0 5a3.
* 0.5a2: 0 5a2.
* 0.5a1: 0 5a1.
* 0.4a4: 0 4a4.
* 0.4a3: 0 4a3.
* 0.4a2: 0 4a2.
* 0.4a1: 0 4a1.
* 0.3a4: 0 3a4.
* 0.3a3: 0 3a3.
* 0.3a2: 0 3a2.
* 0.3a1: 0 3a1.

v50.3.2

* Documentation changes::
* Misc::

v50.3.1

* Documentation changes: Documentation changes<2>.
* Misc: Misc<2>.

v50.3.0

* Changes::

v50.2.0

* Changes: Changes<2>.

v50.1.0

* Changes: Changes<3>.

v50.0.3

* Misc: Misc<3>.

v50.0.2

* Misc: Misc<4>.

v50.0.1

* Misc: Misc<5>.

v50.0.0

* Breaking Changes::
* Changes: Changes<4>.

v49.6.0

* Changes: Changes<5>.

v49.5.0

* Changes: Changes<6>.

v49.4.0

* Changes: Changes<7>.

v49.3.2

* Documentation changes: Documentation changes<3>.
* Misc: Misc<6>.

v49.3.1

* Changes: Changes<8>.

v49.3.0

* Changes: Changes<9>.

v49.2.1

* Misc: Misc<7>.

v49.2.0

* Changes: Changes<10>.

v49.1.3

* Misc: Misc<8>.

v49.1.2

* Changes: Changes<11>.

v49.1.1

* Misc: Misc<9>.

v49.0.1

* Misc: Misc<10>.

v49.1.0

* Changes: Changes<12>.

v49.0.0

* Breaking Changes: Breaking Changes<2>.
* Changes: Changes<13>.
* Misc: Misc<11>.

v48.0.0

* Breaking Changes: Breaking Changes<3>.

v47.3.2

* Misc: Misc<12>.

v47.3.1

* Misc: Misc<13>.

v47.3.0

* Changes: Changes<14>.
* Misc: Misc<14>.

v47.2.0

* Changes: Changes<15>.

v47.1.1

* Documentation changes: Documentation changes<4>.
* Incorporate changes from v44.1.1;: Incorporate changes from v44 1 1.

v44.1.1

* Misc: Misc<15>.

v47.1.0

* Changes: Changes<16>.

v47.0.0

* Breaking Changes: Breaking Changes<4>.
* Changes: Changes<17>.

v46.4.0

* Changes: Changes<18>.

v46.3.0

* Changes: Changes<19>.
* Misc: Misc<16>.

v46.2.0

* Changes: Changes<20>.
* Documentation changes: Documentation changes<5>.
* Misc: Misc<17>.

v46.1.2

* Misc: Misc<18>.

v46.1.0

* Changes: Changes<21>.
* Incorporate changes from v44.1.0;: Incorporate changes from v44 1 0.

v44.1.0

* Changes: Changes<22>.

v46.0.0

* Breaking Changes: Breaking Changes<5>.
* Changes: Changes<23>.
* Documentation changes: Documentation changes<6>.
* Misc: Misc<19>.

v45.3.0

* Changes: Changes<24>.

v45.2.0

* Changes: Changes<25>.
* Misc: Misc<20>.

v45.1.0

* Changes: Changes<26>.

v45.0.0

* Breaking Changes: Breaking Changes<6>.
* Changes: Changes<27>.

v44.0.0

* Breaking Changes: Breaking Changes<7>.

v43.0.0

* Breaking Changes: Breaking Changes<8>.
* Changes: Changes<28>.

v42.0.2

* Changes: Changes<29>.

v42.0.1

* Changes: Changes<30>.

v42.0.0

* Breaking Changes: Breaking Changes<9>.
* Changes: Changes<31>.

v41.6.0

* Changes: Changes<32>.

v41.5.1

* Changes: Changes<33>.

v41.5.0

* Changes: Changes<34>.
* Documentation changes: Documentation changes<7>.
* Misc: Misc<21>.

v41.4.0

* Changes: Changes<35>.

v41.3.0

* Changes: Changes<36>.
* Misc: Misc<22>.

v41.2.0

* Changes: Changes<37>.
* Misc: Misc<23>.

v41.1.0

* Misc: Misc<24>.
* Documentation changes: Documentation changes<8>.

v41.0.1

* Changes: Changes<38>.

v41.0.0

* Breaking Changes: Breaking Changes<10>.

v40.9.0

* Changes: Changes<39>.
* Documentation changes: Documentation changes<9>.

v40.8.0

* Changes: Changes<40>.

v40.7.3

* Changes: Changes<41>.

v40.7.2

* Changes: Changes<42>.

v40.7.1

* Changes: Changes<43>.

v40.7.0

* Breaking Changes: Breaking Changes<11>.
* Changes: Changes<44>.

v40.6.3

* Changes: Changes<45>.

v40.6.2

* Changes: Changes<46>.

v40.6.1

* Changes: Changes<47>.

v40.6.0

* Deprecations::
* Changes: Changes<48>.
* Documentation changes: Documentation changes<10>.
* Misc: Misc<25>.

v40.5.0

* Changes: Changes<49>.
* Documentation changes: Documentation changes<11>.

v40.4.3

* Changes: Changes<50>.

v40.4.2

* Misc: Misc<26>.

v40.4.1

* Changes: Changes<51>.

v40.4.0

* Changes: Changes<52>.

v40.3.0

* Changes: Changes<53>.
* Misc: Misc<27>.

v40.2.0

* Changes: Changes<54>.

v40.1.1

* Changes: Changes<55>.

v40.1.0

* Changes: Changes<56>.
* Misc: Misc<28>.

v40.0.0

* Breaking Changes: Breaking Changes<12>.
* Changes: Changes<57>.
* Documentation changes: Documentation changes<12>.
* Misc: Misc<29>.

v39.2.0

* Changes: Changes<58>.
* Documentation changes: Documentation changes<13>.
* Misc: Misc<30>.

1.0

* Backward-Incompatible Changes::

0.6.3

* setuptools::
* bootstrapping::

0.6.2

* setuptools: setuptools<2>.
* bootstrapping: bootstrapping<2>.

0.6.1

* setuptools: setuptools<3>.
* bootstrapping: bootstrapping<3>.

0.6

* setuptools: setuptools<4>.
* pkg_resources::
* easy_install::



File: setuptools.info,  Node: Building and Distributing Packages with Setuptools,  Next: Build System Support,  Prev: Top,  Up: Top

1 Building and Distributing Packages with Setuptools
****************************************************

‘Setuptools’ is a collection of enhancements to the Python ‘distutils’
that allow developers to more easily build and distribute Python
packages, especially ones that have dependencies on other packages.

Packages built and distributed using ‘setuptools’ look to the user like
ordinary Python packages based on the ‘distutils’.

* Menu:

* Transition to PEP517::


File: setuptools.info,  Node: Transition to PEP517,  Up: Building and Distributing Packages with Setuptools

1.1 Transition to PEP517
========================

Since setuptools no longer serves as the default build tool, one must
explicitly opt in (by providing a ‘pyproject.toml’ file) to use this
library.  The user facing part is provided by tools such as pip and
backend interface is described *note in this document: 5.  The
quickstart provides an overview of the new workflow.

* Menu:

* setuptools Quickstart::
* Package Discovery and Namespace Package::
* Entry Points::
* Dependencies Management in Setuptools::
* Data Files Support::
* “Development Mode”::
* Tagging and “Daily Build” or “Snapshot” Releases::
* Generating Source Distributions::
* Distributing Extensions compiled with Cython::
* Specifying Your Project’s Version::
* Creating distutils Extensions::
* Configuring setup() using setup.cfg files: Configuring setup using setup cfg files.
* New and Changed setup() Keywords: New and Changed setup Keywords.
* Command Reference::
* Using setuptools to package and distribute your project::
* Automatic Resource Extraction::
* Defining Additional Metadata::
* Setting the zip_safe flag::


File: setuptools.info,  Node: setuptools Quickstart,  Next: Package Discovery and Namespace Package,  Up: Transition to PEP517

1.1.1 ‘setuptools’ Quickstart
-----------------------------

* Menu:

* Installation::
* Python packaging at a glance::
* Basic Use::
* Automatic package discovery::
* Entry points and automatic script creation::
* Dependency management::
* Including Data Files::
* Development mode::
* Uploading your package to PyPI::
* Transitioning from setup.py to setup.cfg: Transitioning from setup py to setup cfg.
* Resources on Python packaging::


File: setuptools.info,  Node: Installation,  Next: Python packaging at a glance,  Up: setuptools Quickstart

1.1.1.1 Installation
....................

To install the latest version of setuptools, use:

     pip install --upgrade setuptools


File: setuptools.info,  Node: Python packaging at a glance,  Next: Basic Use,  Prev: Installation,  Up: setuptools Quickstart

1.1.1.2 Python packaging at a glance
....................................

The landscape of Python packaging is shifting and ‘Setuptools’ has
evolved to only provide backend support, no longer being the de-facto
packaging tool in the market.  All python package must provide a
‘pyproject.toml’ and specify the backend (build system) it wants to use.
The distribution can then be generated with whatever tools that provides
a ‘build sdist’-alike functionality.  While this may appear cumbersome,
given the added pieces, it in fact tremendously enhances the portability
of your package.  The change is driven under 517(1).  To learn more
about Python packaging in general, navigate to the bottom(2) of this
page.

   ---------- Footnotes ----------

   (1) https://www.python.org/dev/peps/pep-0517#build-requirements

   (2) Resourcesonpythonpackaging


File: setuptools.info,  Node: Basic Use,  Next: Automatic package discovery,  Prev: Python packaging at a glance,  Up: setuptools Quickstart

1.1.1.3 Basic Use
.................

For basic use of setuptools, you will need a ‘pyproject.toml’ with the
exact following info, which declares you want to use ‘setuptools’ to
package your project:

     [build-system]
     requires = ["setuptools", "wheel"]
     build-backend = "setuptools.build_meta"

Then, you will need a ‘setup.cfg’ to specify your package information,
such as metadata, contents, dependencies, etc.  Here we demonstrate the
minimum

     [metadata]
     name = "mypackage"
     version = 0.0.1

     [options]
     packages = "mypackage"
     install_requires =
       requests
       importlib; python_version == "2.6"

This is what your project would look like:

     ~/mypackage/
         pyproject.toml
         setup.cfg
         mypackage/__init__.py

Then, you need an installer, such as pep517(1) which you can obtain via
‘pip install pep517’.  After downloading it, invoke the installer:

     python -m pep517.build

You now have your distribution ready (e.g.  a ‘tar.gz’ file and a ‘.whl’
file in the ‘dist’ directory), which you can upload to PyPI!

Of course, before you release your project to PyPI, you’ll want to add a
bit more information to your setup script to help people find or learn
about your project.  And maybe your project will have grown by then to
include a few dependencies, and perhaps some data files and scripts.  In
the next few section, we will walk through those additional but
essential information you need to specify to properly package your
project.

   ---------- Footnotes ----------

   (1) https://pypi.org/project/pep517/


File: setuptools.info,  Node: Automatic package discovery,  Next: Entry points and automatic script creation,  Prev: Basic Use,  Up: setuptools Quickstart

1.1.1.4 Automatic package discovery
...................................

For simple projects, it’s usually easy enough to manually add packages
to the ‘packages’ keyword in ‘setup.cfg’.  However, for very large
projects , it can be a big burden to keep the package list updated.
‘setuptools’ therefore provides two convenient tools to ease the burden:
‘find:’ and ‘find_namespace:’.  To use it in your project:

     [options]
     packages = find:

     [options.packages.find] #optional
     include=pkg1, pkg2
     exclude=pk3, pk4

When you pass the above information, alongside other necessary ones,
‘setuptools’ walks through the directory specified in ‘where’ (omitted
here as the package reside in current directory) and filters the
packages it can find following the ‘include’ (default to none), then
remove those that match the ‘exclude’ and return a list of Python
packages.  Note that each entry in the ‘[options.packages.find]’ is
optional.  The above setup also allows you to adopt a ‘src/’ layout.
For more details and advanced use, go to *note Package Discovery and
Namespace Package: c.


File: setuptools.info,  Node: Entry points and automatic script creation,  Next: Dependency management,  Prev: Automatic package discovery,  Up: setuptools Quickstart

1.1.1.5 Entry points and automatic script creation
..................................................

Setuptools support automatic creation of scripts upon installation, that
runs code within your package if you specify them with the
‘entry_points’ keyword.  This is what allows you to run commands like
‘pip install’ instead of having to type ‘python -m pip install’.  To
accomplish this, add the entry_points keyword in your ‘setup.cfg’:

     [options.entry_points]
     console_scripts =
         main = mypkg:some_func

When this project is installed, a ‘main’ script will be installed and
will invoke the ‘some_func’ in the ‘__init__.py’ file when called by the
user.  For detailed usage, including managing the additional or optional
dependencies, go to *note Entry Points: e.


File: setuptools.info,  Node: Dependency management,  Next: Including Data Files,  Prev: Entry points and automatic script creation,  Up: setuptools Quickstart

1.1.1.6 Dependency management
.............................

‘setuptools’ supports automatically installing dependencies when a
package is installed.  The simplest way to include requirement
specifiers is to use the ‘install_requires’ argument to ‘setup.cfg’.  It
takes a string or list of strings containing requirement specifiers (A
version specifier is one of the operators <, >, <=, >=, == or !=,
followed by a version identifier):

     [options]
     install_requires =
         docutils >= 0.3
         requests <= 0.4

When your project is installed, all of the dependencies not already
installed will be located (via PyPI), downloaded, built (if necessary),
and installed.  This, of course, is a simplified scenarios.
‘setuptools’ also provide additional keywords such as ‘setup_requires’
that allows you to install dependencies before running the script, and
‘extras_requires’ that take care of those needed by automatically
generated scripts.  It also provides mechanisms to handle dependencies
that are not in PyPI. For more advanced use, see *note Dependencies
Management in Setuptools: 10.


File: setuptools.info,  Node: Including Data Files,  Next: Development mode,  Prev: Dependency management,  Up: setuptools Quickstart

1.1.1.7 Including Data Files
............................

The distutils have traditionally allowed installation of “data files”,
which are placed in a platform-specific location.  Setuptools offers
three ways to specify data files to be included in your packages.  For
the simpliest use, you can simply use the ‘include_package_data’
keyword:

     [options]
     include_package_data = True

This tells setuptools to install any data files it finds in your
packages.  The data files must be specified via the distutils’
‘MANIFEST.in’ file.  For more details, see *note Data Files Support: 13.


File: setuptools.info,  Node: Development mode,  Next: Uploading your package to PyPI,  Prev: Including Data Files,  Up: setuptools Quickstart

1.1.1.8 Development mode
........................

‘setuptools’ allows you to install a package without copying any files
to your interpretor directory (e.g.  the ‘site-packages’ directory).
This allows you to modify your source code and have the changes take
effect without you having to rebuild and reinstall.  This is currently
incompatible with PEP 517 and therefore it requires a ‘setup.py’ script
with the following content:

     import setuptools
     setuptools.setup()

Then:

     pip install --editable .

This creates a link file in your interpretor site package directory
which associate with your source code.  For more information, see: (WIP)


File: setuptools.info,  Node: Uploading your package to PyPI,  Next: Transitioning from setup py to setup cfg,  Prev: Development mode,  Up: setuptools Quickstart

1.1.1.9 Uploading your package to PyPI
......................................

After generating the distribution files, next step would be to upload
your distribution so others can use it.  This functionality is provided
by twine(1) and we will only demonstrate the basic use here.

   ---------- Footnotes ----------

   (1) https://pypi.org/project/twine/


File: setuptools.info,  Node: Transitioning from setup py to setup cfg,  Next: Resources on Python packaging,  Prev: Uploading your package to PyPI,  Up: setuptools Quickstart

1.1.1.10 Transitioning from ‘setup.py’ to ‘setup.cfg’
.....................................................

To avoid executing arbitary scripts and boilerplate code, we are
transitioning into a full-fledged ‘setup.cfg’ to declare your package
information instead of running ‘setup()’.  This inevitably brings
challenges due to a different syntax.  Here we provide a quick guide to
understanding how ‘setup.cfg’ is parsed by ‘setuptool’ to ease the pain
of transition.


File: setuptools.info,  Node: Resources on Python packaging,  Prev: Transitioning from setup py to setup cfg,  Up: setuptools Quickstart

1.1.1.11 Resources on Python packaging
......................................

Packaging in Python is hard.  Here we provide a list of links for those
that want to learn more.


File: setuptools.info,  Node: Package Discovery and Namespace Package,  Next: Entry Points,  Prev: setuptools Quickstart,  Up: Transition to PEP517

1.1.2 Package Discovery and Namespace Package
---------------------------------------------

     Note: a full specification for the keyword supplied to ‘setup.cfg’
     or ‘setup.py’ can be found at *note keywords reference: 1a.

     Note: the examples provided here are only to demonstrate the
     functionality introduced.  More metadata and options arguments need
     to be supplied if you want to replicate them on your system.  If
     you are completely new to setuptools, the *note quickstart section:
     6. is a good place to start.

‘Setuptools’ provide powerful tools to handle package discovery,
including support for namespace package.  Normally, you would specify
the package to be included manually in the following manner:

     [options]
     #...
     packages =
         mypkg1
         mypkg2

     setup(
         #...
         packages = ['mypkg1', 'mypkg2']
     )

This can get tiresome reallly quickly.  To speed things up, we introduce
two functions provided by setuptools:

     [options]
     packages = find:
     #or
     packages = find_namespace:

     from setuptools import find_packages
     #or
     from setuptools import find_namespace_packages

* Menu:

* Using find; or find_packages: Using find or find_packages.
* Using find_namespace; or find_namespace_packages: Using find_namespace or find_namespace_packages.
* Legacy Namespace Packages::


File: setuptools.info,  Node: Using find or find_packages,  Next: Using find_namespace or find_namespace_packages,  Up: Package Discovery and Namespace Package

1.1.2.1 Using ‘find:’ or ‘find_packages’
........................................

Let’s start with the first tool.  ‘find:’ (‘find_packages’) takes a
source directory and two lists of package name patterns to exclude and
include, and then return a list of ‘str’ representing the packages it
could find.  To use it, consider the following directory

     mypkg/
         src/
             pkg1/__init__.py
             pkg2/__init__.py
             additional/__init__.py

         setup.cfg #or setup.py

To have your setup.cfg or setup.py to automatically include packages
found in ‘src’ that starts with the name ‘pkg’ and not ‘additional’:

     [options]
     packages = find:
     package_dir =
         =src

     [options.packages.find]
     where = src
     include = pkg*
     exclude = additional

     setup(
         #...
         packages = find_packages(
             where = 'src',
             include = ['pkg*',],
             exclude = ['additional',]
         ),
         package_dir = {"":"src"}
         #...
     )


File: setuptools.info,  Node: Using find_namespace or find_namespace_packages,  Next: Legacy Namespace Packages,  Prev: Using find or find_packages,  Up: Package Discovery and Namespace Package

1.1.2.2 Using ‘find_namespace:’ or ‘find_namespace_packages’
............................................................

‘setuptools’ provides the ‘find_namespace:’ (‘find_namespace_packages’)
which behaves similarly to ‘find:’ but works with namespace package.
Before diving in, it is important to have a good understanding of what
namespace packages are.  Here is a quick recap:

Suppose you have two packages named as follows:

     /Users/Desktop/timmins/foo/__init__.py
     /Library/timmins/bar/__init__.py

If both ‘Desktop’ and ‘Library’ are on your ‘PYTHONPATH’, then a
namespace package called ‘timmins’ will be created automatically for you
when you invoke the import mechanism, allowing you to accomplish the
following

     >>> import timmins.foo
     >>> import timmins.bar

as if there is only one ‘timmins’ on your system.  The two packages can
then be distributed separately and installed individually without
affecting the other one.  Suppose you are packaging the ‘foo’ part:

     foo/
         src/
             timmins/foo/__init__.py
         setup.cfg # or setup.py

and you want the ‘foo’ to be automatically included, ‘find:’ won’t work
because timmins doesn’t contain ‘__init__.py’ directly, instead, you
have to use ‘find_namespace:’:

     [options]
     package_dir =
         =src
     packages = find_namespace:

     [options.packages.find_namespace]
     where = src

When you install the zipped distribution, ‘timmins.foo’ would become
available to your interpreter.

You can think of ‘find_namespace:’ as identical to ‘find:’ except it
would count a directory as a package even if it doesn’t contain
‘__init__.py’ file directly.  As a result, this creates an interesting
side effect.  If you organize your package like this:

     foo/
         timmins/
             foo/__init__.py
         setup.cfg # or setup.py
         tests/
             test_foo/__init__.py

a naive ‘find_namespace:’ would include tests as part of your package to
be installed.  A simple way to fix it is to adopt the aforementioned
‘src’ layout.


File: setuptools.info,  Node: Legacy Namespace Packages,  Prev: Using find_namespace or find_namespace_packages,  Up: Package Discovery and Namespace Package

1.1.2.3 Legacy Namespace Packages
.................................

The fact you can create namespace package so effortlessly above is
credited to PEP 420(1).  It use to be more cumbersome to accomplish the
same result.  Historically, there were two methods to create namespace
packages.  One is the ‘pkg_resources’ style supported by ‘setuptools’
and the other one being ‘pkgutils’ style offered by ‘pkgutils’ module in
Python.  Both are now considered deprecated despite the fact they still
linger in many existing packages.  These two differ in many subtle yet
significant aspects and you can find out more on Python packaging user
guide(2)

* Menu:

* pkg_resource style namespace package::
* pkgutil style namespace package::

   ---------- Footnotes ----------

   (1) https://www.python.org/dev/peps/pep-0420/

   (2) https://packaging.python.org/guides/packaging-namespace-packages/


File: setuptools.info,  Node: pkg_resource style namespace package,  Next: pkgutil style namespace package,  Up: Legacy Namespace Packages

1.1.2.4 ‘pkg_resource’ style namespace package
..............................................

This is the method ‘setuptools’ directly supports.  Starting with the
same layout, there are two pieces you need to add to it.  First, an
‘__init__.py’ file directly under your namespace package directory that
contains the following:

     __import__("pkg_resources").declare_namespace(__name__)

And the ‘namespace_packages’ keyword in your ‘setup.cfg’ or ‘setup.py’:

     [options]
     namespace_packages = timmins

     setup(
         # ...
         namespace_packages = ['timmins']
     )

And your directory should look like this

     /foo/
         src/
             timmins/
                 __init__.py
                 foo/__init__.py
         setup.cfg #or setup.py

Repeat the same for other packages and you can achieve the same result
as the previous section.


File: setuptools.info,  Node: pkgutil style namespace package,  Prev: pkg_resource style namespace package,  Up: Legacy Namespace Packages

1.1.2.5 ‘pkgutil’ style namespace package
.........................................

This method is almost identical to the ‘pkg_resource’ except that the
‘namespace_packages’ declaration is omitted and the ‘__init__.py’ file
contains the following:

     __path__ = __import__('pkgutil').extend_path(__path__, __name__)

The project layout remains the same and ‘setup.cfg’ remains the same.


File: setuptools.info,  Node: Entry Points,  Next: Dependencies Management in Setuptools,  Prev: Package Discovery and Namespace Package,  Up: Transition to PEP517

1.1.3 Entry Points
------------------

Packages may provide commands to be run at the console (console
scripts), such as the ‘pip’ command.  These commands are defined for a
package as a specific kind of entry point in the ‘setup.cfg’ or
‘setup.py’.

* Menu:

* Console Scripts::
* Advertising Behavior::
* Dependency Management::


File: setuptools.info,  Node: Console Scripts,  Next: Advertising Behavior,  Up: Entry Points

1.1.3.1 Console Scripts
.......................

First consider an example without entry points.  Imagine a package
defined thus:

     timmins/
         timmins/__init__.py
         timmins/__main__.py
         setup.cfg # or setup.py
         #other necessary files

with ‘__init__.py’ as:

     def helloworld():
         print("Hello world")

and ‘__main__.py’ providing a hook:

     from . import hello_world
     if __name__ == '__main__':
         hello_world()

After installing the package, the function may be invoked through the
runpy(1) module:

     python -m timmins

Adding a console script entry point allows the package to define a
user-friendly name for installers of the package to execute.  Installers
like pip will create wrapper scripts to execute a function.  In the
above example, to create a command ‘hello-world’ that invokes
‘timmins.hello_world’, add a console script entry point to ‘setup.cfg’:

     [options.entry_points]
     console_scripts =
         hello-world = timmins:hello_world

After installing the package, a user may invoke that function by simply
calling ‘hello-world’ on the command line.

The syntax for entry points is specified as follows:

     <name> = [<package>.[<subpackage>.]]<module>[:<object>.<object>]

where ‘name’ is the name for the script you want to create, the left
hand side of ‘:’ is the module that contains your function and the right
hand side is the object you want to invoke (e.g.  a function).

In addition to ‘console_scripts’, Setuptools supports ‘gui_scripts’,
which will launch a GUI application without running in a terminal
window.

   ---------- Footnotes ----------

   (1) https://docs.python.org/3/library/runpy.html


File: setuptools.info,  Node: Advertising Behavior,  Next: Dependency Management,  Prev: Console Scripts,  Up: Entry Points

1.1.3.2 Advertising Behavior
............................

Console scripts are one use of the more general concept of entry points.
Entry points more generally allow a packager to advertise behavior for
discovery by other libraries and applications.  This feature enables
“plug-in”-like functionality, where one library solicits entry points
and any number of other libraries provide those entry points.

A good example of this plug-in behavior can be seen in pytest
plugins(1), where pytest is a test framework that allows other libraries
to extend or modify its functionality through the ‘pytest11’ entry
point.

The console scripts work similarly, where libraries advertise their
commands and tools like ‘pip’ create wrapper scripts that invoke those
commands.

For a project wishing to solicit entry points, Setuptools recommends the
importlib.metadata(2) module (part of stdlib since Python 3.8) or its
backport, importlib_metadata(3).

For example, to find the console script entry points from the example
above:

     >>> from importlib import metadata
     >>> eps = metadata.entry_points()['console_scripts']

‘eps’ is now a list of ‘EntryPoint’ objects, one of which corresponds to
the ‘hello-world = timmins:hello_world’ defined above.  Each
‘EntryPoint’ contains the ‘name’, ‘group’, and ‘value’.  It also
supplies a ‘.load()’ method to import and load that entry point (module
or object).

     [options.entry_points]
     my.plugins =
         hello-world = timmins:hello_world

Then, a different project wishing to load ‘my.plugins’ plugins could run
the following routine to load (and invoke) such plugins:

     >>> from importlib import metadata
     >>> eps = metadata.entry_points()['my.plugins']
     >>> for ep in eps:
     ...     plugin = ep.load()
     ...     plugin()

The project soliciting the entry points needs not to have any dependency
or prior knowledge about the libraries implementing the entry points,
and downstream users are able to compose functionality by pulling
together libraries implementing the entry points.

   ---------- Footnotes ----------

   (1) https://docs.pytest.org/en/latest/writing_plugins.html

   (2) https://docs.python.org/3/library/importlib.metadata.html

   (3) https://pypi.org/project/importlib_metadata


File: setuptools.info,  Node: Dependency Management,  Prev: Advertising Behavior,  Up: Entry Points

1.1.3.3 Dependency Management
.............................

Some entry points may require additional dependencies to properly
function.  For such an entry point, declare in square brakets any number
of dependency ‘extras’ following the entry point definition.  Such entry
points will only be viable if their extras were declared and installed.
See the *note guide on dependencies management: 10. for more information
on defining extra requirements.  Consider from the above example:

     [options.entry_points]
     console_scripts =
         hello-world = timmins:hello_world [pretty-printer]

In this case, the ‘hello-world’ script is only viable if the
‘pretty-printer’ extra is indicated, and so a plugin host might exclude
that entry point (i.e.  not install a console script) if the relevant
extra dependencies are not installed.


File: setuptools.info,  Node: Dependencies Management in Setuptools,  Next: Data Files Support,  Prev: Entry Points,  Up: Transition to PEP517

1.1.4 Dependencies Management in Setuptools
-------------------------------------------

There are three types of dependency styles offered by setuptools: 1)
build system requirement, required dependency and 3) optional
dependency.

     Note: Packages that are added to dependency can be optionally
     specified with the version by following PEP 440(1)

* Menu:

* Build system requirement::
* Declaring required dependency::
* Optional dependencies::
* Python requirement::

   ---------- Footnotes ----------

   (1) https://www.python.org/dev/peps/pep-0440/


File: setuptools.info,  Node: Build system requirement,  Next: Declaring required dependency,  Up: Dependencies Management in Setuptools

1.1.4.1 Build system requirement
................................

* Menu:

* Package requirement::


File: setuptools.info,  Node: Package requirement,  Up: Build system requirement

1.1.4.2 Package requirement
...........................

After organizing all the scripts and files and getting ready for
packaging, there needs to be a way to tell Python what programs it need
to actually do the packgaging (in our case, ‘setuptools’ of course).
Usually, you also need the ‘wheel’ package as well since it is
recommended that you upload a ‘.whl’ file to PyPI alongside your
‘.tar.gz’ file.  Unlike the other two types of dependency keyword, this
one is specified in your ‘pyproject.toml’ file (if you have forgot what
this is, go to *note setuptools Quickstart: 6. or (WIP)):

     [build-system]
     requires = ["setuptools", "wheel"]
     #...

     Note: This used to be accomplished with the ‘setup_requires’
     keyword but is now considered deprecated in favor of the PEP 517
     style described above.  To peek into how this legacy keyword is
     used, consult our *note guide on deprecated practice (WIP): 2a.


File: setuptools.info,  Node: Declaring required dependency,  Next: Optional dependencies,  Prev: Build system requirement,  Up: Dependencies Management in Setuptools

1.1.4.3 Declaring required dependency
.....................................

This is where a package declares its core dependencies, without which it
won’t be able to run.  ‘setuptools’ support automatically download and
install these dependencies when the package is installed.  Although
there is more finess to it, let’s start with a simple example.

     [options]
     #...
     install_requires =
         docutils
         BazSpam ==1.1

     setup(
         #...,
         install_requires = [
             'docutils',
             'BazSpam ==1.1'
         ]
     )

When your project is installed (e.g.  using pip), all of the
dependencies not already installed will be located (via PyPI),
downloaded, built (if necessary), and installed and 2) Any scripts in
your project will be installed with wrappers that verify the
availability of the specified dependencies at runtime.

* Menu:

* Platform specific dependencies::
* Dependencies that aren’t in PyPI::


File: setuptools.info,  Node: Platform specific dependencies,  Next: Dependencies that aren’t in PyPI,  Up: Declaring required dependency

1.1.4.4 Platform specific dependencies
......................................

Setuptools offer the capability to evaluate certain conditions before
blindly installing everything listed in ‘install_requires’.  This is
great for platform specific dependencies.  For example, the ‘enum’
package was added in Python 3.4, therefore, package that depends on it
can elect to install it only when the Python version is older than 3.4.
To accomplish this

     [options]
     #...
     install_requires =
         enum34;python_version<'3.4'

     setup(
         #...
         install_requires=[
             "enum34;python_version<'3.4'",]
     )

Similarly, if you also wish to declare ‘pywin32’ with a minimal version
of 1.0 and only install it if the user is using a Windows operating
system:

     [options]
     #...
     install_requires =
         enum34;python_version<'3.4'
         pywin32 >= 1.0;platform_system=='Windows'

     setup(
         #...
         install_requires=[
             "enum34;python_version<'3.4'",
             "pywin32 >= 1.0;platform_system=='Windows'"
             ]
     )

The environmental markers that may be used for testing platform types
are detailed in PEP 508(1).

   ---------- Footnotes ----------

   (1) https://www.python.org/dev/peps/pep-0508/


File: setuptools.info,  Node: Dependencies that aren’t in PyPI,  Prev: Platform specific dependencies,  Up: Declaring required dependency

1.1.4.5 Dependencies that aren’t in PyPI
........................................

     Warning: Dependency links support has been dropped by pip starting
     with version 19.0 (released 2019-01-22).

If your project depends on packages that don’t exist on PyPI, you may
still be able to depend on them, as long as they are available for
download as:

   - an egg, in the standard distutils ‘sdist’ format,

   - a single ‘.py’ file, or

   - a VCS repository (Subversion, Mercurial, or Git).

You just need to add some URLs to the ‘dependency_links’ argument to
‘setup()’.

The URLs must be either:

  1. direct download URLs,

  2. the URLs of web pages that contain direct download links, or

  3. the repository’s URL

In general, it’s better to link to web pages, because it is usually less
complex to update a web page than to release a new version of your
project.  You can also use a SourceForge ‘showfiles.php’ link in the
case where a package you depend on is distributed via SourceForge.

If you depend on a package that’s distributed as a single ‘.py’ file,
you must include an ‘"#egg=project-version"’ suffix to the URL, to give
a project name and version number.  (Be sure to escape any dashes in the
name or version by replacing them with underscores.)  EasyInstall will
recognize this suffix and automatically create a trivial ‘setup.py’ to
wrap the single ‘.py’ file as an egg.

In the case of a VCS checkout, you should also append
‘#egg=project-version’ in order to identify for what package that
checkout should be used.  You can append ‘@REV’ to the URL’s path
(before the fragment) to specify a revision.  Additionally, you can also
force the VCS being used by prepending the URL with a certain prefix.
Currently available are:

   - ‘svn+URL’ for Subversion,

   - ‘git+URL’ for Git, and

   - ‘hg+URL’ for Mercurial

A more complete example would be:

     ‘vcs+proto://host/path@revision#egg=project-version’

Be careful with the version.  It should match the one inside the project
files.  If you want to disregard the version, you have to omit it both
in the ‘requires’ and in the URL’s fragment.

This will do a checkout (or a clone, in Git and Mercurial parlance) to a
temporary folder and run ‘setup.py bdist_egg’.

The ‘dependency_links’ option takes the form of a list of URL strings.
For example, this will cause a search of the specified page for eggs or
source distributions, if the package’s dependencies aren’t already
installed:

     [options]
     #...
     dependency_links = http://peak.telecommunity.com/snapshots/

     setup(
         #...
         dependency_links=[
             "http://peak.telecommunity.com/snapshots/"
         ],
     )


File: setuptools.info,  Node: Optional dependencies,  Next: Python requirement,  Prev: Declaring required dependency,  Up: Dependencies Management in Setuptools

1.1.4.6 Optional dependencies
.............................

Setuptools allows you to declare dependencies that only get installed
under specific circumstances.  These dependencies are specified with
‘extras_require’ keyword and are only installed if another package
depends on it (either directly or indirectly) This makes it convenient
to declare dependencies for ancillary functions such as “tests” and
“docs”.

     Note: ‘tests_require’ is now deprecated

For example, Package-A offers optional PDF support and requires two
other dependencies for it to work:

     [metadata]
     name = Package-A

     [options.extras_require]
     PDF = ReportLab>=1.2; RXP

     setup(
         name="Project-A",
         #...
         extras_require={
             "PDF":  ["ReportLab>=1.2", "RXP"],
         }
     )

The name ‘PDF’ is an arbitary identifier of such a list of dependencies,
to which other components can refer and have them installed.  There are
two common use cases.

First is the console_scripts entry point:

     [metadata]
     name = Project A
     #...

     [options]
     #...
     entry_points=
         [console_scripts]
         rst2pdf = project_a.tools.pdfgen [PDF]
         rst2html = project_a.tools.htmlgen

     setup(
         name = "Project-A"
         #...,
         entry_points={
             "console_scripts": [
                 "rst2pdf = project_a.tools.pdfgen [PDF]",
                 "rst2html = project_a.tools.htmlgen",
             ],
         }
     )

When the script ‘rst2pdf’ is run, it will trigger the installation of
the two dependencies ‘PDF’ maps to.

The second use case is that other package can use this “extra” for their
own dependencies.  For example, if “Project-B” needs “project A” with
PDF support installed, it might declare the dependency like this:

     [metadata]
     name = Project-B
     #...

     [options]
     #...
     install_requires =
         Project-A[PDF]

     setup(
         name="Project-B",
         install_requires=["Project-A[PDF]"],
         ...
     )

This will cause ReportLab to be installed along with project A, if
project B is installed – even if project A was already installed.  In
this way, a project can encapsulate groups of optional “downstream
dependencies” under a feature name, so that packages that depend on it
don’t have to know what the downstream dependencies are.  If a later
version of Project A builds in PDF support and no longer needs
ReportLab, or if it ends up needing other dependencies besides ReportLab
in order to provide PDF support, Project B’s setup information does not
need to change, but the right packages will still be installed if
needed.

     Note: Best practice: if a project ends up not needing any other
     packages to support a feature, it should keep an empty requirements
     list for that feature in its ‘extras_require’ argument, so that
     packages depending on that feature don’t break (due to an invalid
     feature name).


File: setuptools.info,  Node: Python requirement,  Prev: Optional dependencies,  Up: Dependencies Management in Setuptools

1.1.4.7 Python requirement
..........................

In some cases, you might need to specify the minimum required python
version.  This is handled with the ‘python_requires’ keyword supplied to
‘setup.cfg’ or ‘setup.py’.

Example WIP


File: setuptools.info,  Node: Data Files Support,  Next: “Development Mode”,  Prev: Dependencies Management in Setuptools,  Up: Transition to PEP517

1.1.5 Data Files Support
------------------------

The distutils have traditionally allowed installation of “data files”,
which are placed in a platform-specific location.  However, the most
common use case for data files distributed with a package is for use
`by' the package, usually by including the data files in the package
directory.

Setuptools offers three ways to specify data files to be included in
your packages.  First, you can simply use the ‘include_package_data’
keyword, e.g.:

     from setuptools import setup, find_packages
     setup(
         ...
         include_package_data=True
     )

This tells setuptools to install any data files it finds in your
packages.  The data files must be specified via the distutils’
‘MANIFEST.in’ file.  (They can also be tracked by a revision control
system, using an appropriate plugin.  See the section below on *note
Adding Support for Revision Control Systems: 32. for information on how
to write such plugins.)

If you want finer-grained control over what files are included (for
example, if you have documentation files in your package directories and
want to exclude them from installation), then you can also use the
‘package_data’ keyword, e.g.:

     from setuptools import setup, find_packages
     setup(
         ...
         package_data={
             # If any package contains *.txt or *.rst files, include them:
             "": ["*.txt", "*.rst"],
             # And include any *.msg files found in the "hello" package, too:
             "hello": ["*.msg"],
         }
     )

The ‘package_data’ argument is a dictionary that maps from package names
to lists of glob patterns.  The globs may include subdirectory names, if
the data files are contained in a subdirectory of the package.  For
example, if the package tree looks like this:

     setup.py
     src/
         mypkg/
             __init__.py
             mypkg.txt
             data/
                 somefile.dat
                 otherdata.dat

The setuptools setup file might look like this:

     from setuptools import setup, find_packages
     setup(
         ...
         packages=find_packages("src"),  # include all packages under src
         package_dir={"": "src"},   # tell distutils packages are under src

         package_data={
             # If any package contains *.txt files, include them:
             "": ["*.txt"],
             # And include any *.dat files found in the "data" subdirectory
             # of the "mypkg" package, also:
             "mypkg": ["data/*.dat"],
         }
     )

Notice that if you list patterns in ‘package_data’ under the empty
string, these patterns are used to find files in every package, even
ones that also have their own patterns listed.  Thus, in the above
example, the ‘mypkg.txt’ file gets included even though it’s not listed
in the patterns for ‘mypkg’.

Also notice that if you use paths, you `must' use a forward slash (‘/’)
as the path separator, even if you are on Windows.  Setuptools
automatically converts slashes to appropriate platform-specific
separators at build time.

If datafiles are contained in a subdirectory of a package that isn’t a
package itself (no ‘__init__.py’), then the subdirectory names (or ‘*’)
are required in the ‘package_data’ argument (as shown above with
‘"data/*.dat"’).

When building an ‘sdist’, the datafiles are also drawn from the
‘package_name.egg-info/SOURCES.txt’ file, so make sure that this is
removed if the ‘setup.py’ ‘package_data’ list is updated before calling
‘setup.py’.

(Note: although the ‘package_data’ argument was previously only
available in ‘setuptools’, it was also added to the Python ‘distutils’
package as of Python 2.4; there is some documentation for the feature(1)
available on the python.org website.  If using the setuptools-specific
‘include_package_data’ argument, files specified by ‘package_data’ will
`not' be automatically added to the manifest unless they are listed in
the MANIFEST.in file.)

Sometimes, the ‘include_package_data’ or ‘package_data’ options alone
aren’t sufficient to precisely define what files you want included.  For
example, you may want to include package README files in your revision
control system and source distributions, but exclude them from being
installed.  So, setuptools offers an ‘exclude_package_data’ option as
well, that allows you to do things like this:

     from setuptools import setup, find_packages
     setup(
         ...
         packages=find_packages("src"),  # include all packages under src
         package_dir={"": "src"},   # tell distutils packages are under src

         include_package_data=True,    # include everything in source control

         # ...but exclude README.txt from all packages
         exclude_package_data={"": ["README.txt"]},
     )

The ‘exclude_package_data’ option is a dictionary mapping package names
to lists of wildcard patterns, just like the ‘package_data’ option.
And, just as with that option, a key of ‘""’ will apply the given
pattern(s) to all packages.  However, any files that match these
patterns will be `excluded' from installation, even if they were listed
in ‘package_data’ or were included as a result of using
‘include_package_data’.

In summary, the three options allow you to:

‘include_package_data’

     Accept all data files and directories matched by ‘MANIFEST.in’.

‘package_data’

     Specify additional patterns to match files that may or may not be
     matched by ‘MANIFEST.in’ or found in source control.

‘exclude_package_data’

     Specify patterns for data files and directories that should `not'
     be included when a package is installed, even if they would
     otherwise have been included due to the use of the preceding
     options.

NOTE: Due to the way the distutils build process works, a data file that
you include in your project and then stop including may be “orphaned” in
your project’s build directories, requiring you to run ‘setup.py clean
--all’ to fully remove them.  This may also be important for your users
and contributors if they track intermediate revisions of your project
using Subversion; be sure to let them know when you make changes that
remove files from inclusion so they can run ‘setup.py clean --all’.

* Menu:

* Accessing Data Files at Runtime::
* Non-Package Data Files::

   ---------- Footnotes ----------

   (1) 
https://docs.python.org/3/distutils/setupscript.html#installing-package-data


File: setuptools.info,  Node: Accessing Data Files at Runtime,  Next: Non-Package Data Files,  Up: Data Files Support

1.1.5.1 Accessing Data Files at Runtime
.......................................

Typically, existing programs manipulate a package’s ‘__file__’ attribute
in order to find the location of data files.  However, this manipulation
isn’t compatible with PEP 302-based import hooks, including importing
from zip files and Python Eggs.  It is strongly recommended that, if you
are using data files, you should use the *note ResourceManager API: 35.
of ‘pkg_resources’ to access them.  The ‘pkg_resources’ module is
distributed as part of setuptools, so if you’re using setuptools to
distribute your package, there is no reason not to use its resource
management API. See also Importlib Resources(1) for a quick example of
converting code that uses ‘__file__’ to use ‘pkg_resources’ instead.

   ---------- Footnotes ----------

   (1) 
https://docs.python.org/3/library/importlib.html#module-importlib.resources


File: setuptools.info,  Node: Non-Package Data Files,  Prev: Accessing Data Files at Runtime,  Up: Data Files Support

1.1.5.2 Non-Package Data Files
..............................

Historically, ‘setuptools’ by way of ‘easy_install’ would encapsulate
data files from the distribution into the egg (see the old docs(1)).  As
eggs are deprecated and pip-based installs fall back to the
platform-specific location for installing data files, there is no
supported facility to reliably retrieve these resources.

Instead, the PyPA recommends that any data files you wish to be
accessible at run time be included in the package.

   ---------- Footnotes ----------

   (1) 
https://github.com/pypa/setuptools/blob/52aacd5b276fedd6849c3a648a0014f5da563e93/docs/setuptools.txt#L970-L1001


File: setuptools.info,  Node: “Development Mode”,  Next: Tagging and “Daily Build” or “Snapshot” Releases,  Prev: Data Files Support,  Up: Transition to PEP517

1.1.6 “Development Mode”
------------------------

Under normal circumstances, the ‘distutils’ assume that you are going to
build a distribution of your project, not use it in its “raw” or
“unbuilt” form.  If you were to use the ‘distutils’ that way, you would
have to rebuild and reinstall your project every time you made a change
to it during development.

Another problem that sometimes comes up with the ‘distutils’ is that you
may need to do development on two related projects at the same time.
You may need to put both projects’ packages in the same directory to run
them, but need to keep them separate for revision control purposes.  How
can you do this?

Setuptools allows you to deploy your projects for use in a common
directory or staging area, but without copying any files.  Thus, you can
edit each project’s code in its checkout directory, and only need to run
build commands when you change a project’s C extensions or similarly
compiled files.  You can even deploy a project into another project’s
checkout directory, if that’s your preferred way of working (as opposed
to using a common independent staging area or the site-packages
directory).

To do this, use the ‘setup.py develop’ command.  It works very similarly
to ‘setup.py install’, except that it doesn’t actually install anything.
Instead, it creates a special ‘.egg-link’ file in the deployment
directory, that links to your project’s source code.  And, if your
deployment directory is Python’s ‘site-packages’ directory, it will also
update the ‘easy-install.pth’ file to include your project’s source
code, thereby making it available on ‘sys.path’ for all programs using
that Python installation.

If you have enabled the ‘use_2to3’ flag, then of course the ‘.egg-link’
will not link directly to your source code when run under Python 3,
since that source code would be made for Python 2 and not work under
Python 3.  Instead the ‘setup.py develop’ will build Python 3 code under
the ‘build’ directory, and link there.  This means that after doing code
changes you will have to run ‘setup.py build’ before these changes are
picked up by your Python 3 installation.

In addition, the ‘develop’ command creates wrapper scripts in the target
script directory that will run your in-development scripts after
ensuring that all your ‘install_requires’ packages are available on
‘sys.path’.

You can deploy the same project to multiple staging areas, e.g.  if you
have multiple projects on the same machine that are sharing the same
project you’re doing development work.

When you’re done with a given development task, you can remove the
project source from a staging area using ‘setup.py develop --uninstall’,
specifying the desired staging area if it’s not the default.

There are several options to control the precise behavior of the
‘develop’ command; see the section on the *note develop: 3a. command
below for more details.

Note that you can also apply setuptools commands to non-setuptools
projects, using commands like this:

     python -c "import setuptools; with open('setup.py') as f: exec(compile(f.read(), 'setup.py', 'exec'))" develop

That is, you can simply list the normal setup commands and options
following the quoted part.


File: setuptools.info,  Node: Tagging and “Daily Build” or “Snapshot” Releases,  Next: Generating Source Distributions,  Prev: “Development Mode”,  Up: Transition to PEP517

1.1.7 Tagging and “Daily Build” or “Snapshot” Releases
------------------------------------------------------

When a set of related projects are under development, it may be
important to track finer-grained version increments than you would
normally use for e.g.  “stable” releases.  While stable releases might
be measured in dotted numbers with alpha/beta/etc.  status codes,
development versions of a project often need to be tracked by revision
or build number or even build date.  This is especially true when
projects in development need to refer to one another, and therefore may
literally need an up-to-the-minute version of something!

To support these scenarios, ‘setuptools’ allows you to “tag” your source
and egg distributions by adding one or more of the following to the
project’s “official” version identifier:

   * A manually-specified pre-release tag, such as “build” or “dev”, or
     a manually-specified post-release tag, such as a build or revision
     number (‘--tag-build=STRING, -bSTRING’)

   * An 8-character representation of the build date (‘--tag-date, -d’),
     as a postrelease tag

You can add these tags by adding ‘egg_info’ and the desired options to
the command line ahead of the ‘sdist’ or ‘bdist’ commands that you want
to generate a daily build or snapshot for.  See the section below on the
*note egg_info: 3d. command for more details.

(Also, before you release your project, be sure to see the section above
on *note Specifying Your Project’s Version: 3e. for more information
about how pre- and post-release tags affect how version numbers are
interpreted.  This is important in order to make sure that dependency
processing tools will know which versions of your project are newer than
others.)

Finally, if you are creating builds frequently, and either building them
in a downloadable location or are copying them to a distribution server,
you should probably also check out the *note rotate: 3f. command, which
lets you automatically delete all but the N most-recently-modified
distributions matching a glob pattern.  So, you can use a command line
like:

     setup.py egg_info -rbDEV bdist_egg rotate -m.egg -k3

to build an egg whose version info includes “DEV-rNNNN” (where NNNN is
the most recent Subversion revision that affected the source tree), and
then delete any egg files from the distribution directory except for the
three that were built most recently.

If you have to manage automated builds for multiple packages, each with
different tagging and rotation policies, you may also want to check out
the *note alias: 40. command, which would let each package define an
alias like ‘daily’ that would perform the necessary tag, build, and
rotate commands.  Then, a simpler script or cron job could just run
‘setup.py daily’ in each project directory.  (And, you could also define
sitewide or per-user default versions of the ‘daily’ alias, so that
projects that didn’t define their own would use the appropriate
defaults.)


File: setuptools.info,  Node: Generating Source Distributions,  Next: Distributing Extensions compiled with Cython,  Prev: Tagging and “Daily Build” or “Snapshot” Releases,  Up: Transition to PEP517

1.1.8 Generating Source Distributions
-------------------------------------

‘setuptools’ enhances the distutils’ default algorithm for source file
selection with pluggable endpoints for looking up files to include.  If
you are using a revision control system, and your source distributions
only need to include files that you’re tracking in revision control, use
a corresponding plugin instead of writing a ‘MANIFEST.in’ file.  See the
section below on *note Adding Support for Revision Control Systems: 32.
for information on plugins.

If you need to include automatically generated files, or files that are
kept in an unsupported revision control system, you’ll need to create a
‘MANIFEST.in’ file to specify any files that the default file location
algorithm doesn’t catch.  See the distutils documentation for more
information on the format of the ‘MANIFEST.in’ file.

But, be sure to ignore any part of the distutils documentation that
deals with ‘MANIFEST’ or how it’s generated from ‘MANIFEST.in’;
setuptools shields you from these issues and doesn’t work the same way
in any case.  Unlike the distutils, setuptools regenerates the source
distribution manifest file every time you build a source distribution,
and it builds it inside the project’s ‘.egg-info’ directory, out of the
way of your main project directory.  You therefore need not worry about
whether it is up-to-date or not.

Indeed, because setuptools’ approach to determining the contents of a
source distribution is so much simpler, its ‘sdist’ command omits nearly
all of the options that the distutils’ more complex ‘sdist’ process
requires.  For all practical purposes, you’ll probably use only the
‘--formats’ option, if you use any option at all.

* Menu:

* Making “Official” (Non-Snapshot) Releases: Making “Official” Non-Snapshot Releases.


File: setuptools.info,  Node: Making “Official” Non-Snapshot Releases,  Up: Generating Source Distributions

1.1.8.1 Making “Official” (Non-Snapshot) Releases
.................................................

When you make an official release, creating source or binary
distributions, you will need to override the tag settings from
‘setup.cfg’, so that you don’t end up registering versions like
‘foobar-0.7a1.dev-r34832’.  This is easy to do if you are developing on
the trunk and using tags or branches for your releases - just make the
change to ‘setup.cfg’ after branching or tagging the release, so the
trunk will still produce development snapshots.

Alternately, if you are not branching for releases, you can override the
default version options on the command line, using something like:

     setup.py egg_info -Db "" sdist bdist_egg

The first part of this command (‘egg_info -Db ""’) will override the
configured tag information, before creating source and binary eggs.
Thus, these commands will use the plain version from your ‘setup.py’,
without adding the build designation string.

Of course, if you will be doing this a lot, you may wish to create a
personal alias for this operation, e.g.:

     setup.py alias -u release egg_info -Db ""

You can then use it like this:

     setup.py release sdist bdist_egg

Or of course you can create more elaborate aliases that do all of the
above.  See the sections below on the *note egg_info: 3d. and *note
alias: 40. commands for more ideas.


File: setuptools.info,  Node: Distributing Extensions compiled with Cython,  Next: Specifying Your Project’s Version,  Prev: Generating Source Distributions,  Up: Transition to PEP517

1.1.9 Distributing Extensions compiled with Cython
--------------------------------------------------

‘setuptools’ will detect at build time whether Cython is installed or
not.  If Cython is not found ‘setuptools’ will ignore pyx files.

To ensure Cython is available, include Cython in the build-requires
section of your pyproject.toml:

     [build-system]
     requires=[..., "cython"]

Built with pip 10 or later, that declaration is sufficient to include
Cython in the build.  For broader compatibility, declare the dependency
in your setup-requires of setup.cfg:

     [options]
     setup_requires =
         ...
         cython

As long as Cython is present in the build environment, ‘setuptools’
includes transparent support for building Cython extensions, as long as
extensions are defined using ‘setuptools.Extension’.

If you follow these rules, you can safely list ‘.pyx’ files as the
source of your ‘Extension’ objects in the setup script.  If it is, then
‘setuptools’ will use it.

Of course, for this to work, your source distributions must include the
C code generated by Cython, as well as your original ‘.pyx’ files.  This
means that you will probably want to include current ‘.c’ files in your
revision control system, rebuilding them whenever you check changes in
for the ‘.pyx’ source files.  This will ensure that people tracking your
project in a revision control system will be able to build it even if
they don’t have Cython installed, and that your source releases will be
similarly usable with or without Cython.


File: setuptools.info,  Node: Specifying Your Project’s Version,  Next: Creating distutils Extensions,  Prev: Distributing Extensions compiled with Cython,  Up: Transition to PEP517

1.1.10 Specifying Your Project’s Version
----------------------------------------

Setuptools can work well with most versioning schemes; there are,
however, a few special things to watch out for, in order to ensure that
setuptools and other tools can always tell what version of your package
is newer than another version.  Knowing these things will also help you
correctly specify what versions of other projects your project depends
on.

A version consists of an alternating series of release numbers and
pre-release or post-release tags.  A release number is a series of
digits punctuated by dots, such as ‘2.4’ or ‘0.5’.  Each series of
digits is treated numerically, so releases ‘2.1’ and ‘2.1.0’ are
different ways to spell the same release number, denoting the first
subrelease of release 2.  But ‘2.10’ is the `tenth' subrelease of
release 2, and so is a different and newer release from ‘2.1’ or
‘2.1.0’.  Leading zeros within a series of digits are also ignored, so
‘2.01’ is the same as ‘2.1’, and different from ‘2.0.1’.

Following a release number, you can have either a pre-release or
post-release tag.  Pre-release tags make a version be considered `older'
than the version they are appended to.  So, revision ‘2.4’ is `newer'
than revision ‘2.4c1’, which in turn is newer than ‘2.4b1’ or ‘2.4a1’.
Postrelease tags make a version be considered `newer' than the version
they are appended to.  So, revisions like ‘2.4-1’ and ‘2.4pl3’ are newer
than ‘2.4’, but are `older' than ‘2.4.1’ (which has a higher release
number).

A pre-release tag is a series of letters that are alphabetically before
“final”.  Some examples of prerelease tags would include ‘alpha’,
‘beta’, ‘a’, ‘c’, ‘dev’, and so on.  You do not have to place a dot or
dash before the prerelease tag if it’s immediately after a number, but
it’s okay to do so if you prefer.  Thus, ‘2.4c1’ and ‘2.4.c1’ and
‘2.4-c1’ all represent release candidate 1 of version ‘2.4’, and are
treated as identical by setuptools.

In addition, there are three special prerelease tags that are treated as
if they were the letter ‘c’: ‘pre’, ‘preview’, and ‘rc’.  So, version
‘2.4rc1’, ‘2.4pre1’ and ‘2.4preview1’ are all the exact same version as
‘2.4c1’, and are treated as identical by setuptools.

A post-release tag is either a series of letters that are alphabetically
greater than or equal to “final”, or a dash (‘-’).  Post-release tags
are generally used to separate patch numbers, port numbers, build
numbers, revision numbers, or date stamps from the release number.  For
example, the version ‘2.4-r1263’ might denote Subversion revision 1263
of a post-release patch of version ‘2.4’.  Or you might use
‘2.4-20051127’ to denote a date-stamped post-release.

Notice that after each pre or post-release tag, you are free to place
another release number, followed again by more pre- or post-release
tags.  For example, ‘0.6a9.dev-r41475’ could denote Subversion revision
41475 of the in- development version of the ninth alpha of release 0.6.
Notice that ‘dev’ is a pre-release tag, so this version is a `lower'
version number than ‘0.6a9’, which would be the actual ninth alpha of
release 0.6.  But the ‘-r41475’ is a post-release tag, so this version
is `newer' than ‘0.6a9.dev’.

For the most part, setuptools’ interpretation of version numbers is
intuitive, but here are a few tips that will keep you out of trouble in
the corner cases:

   * Don’t stick adjoining pre-release tags together without a dot or
     number between them.  Version ‘1.9adev’ is the ‘adev’ prerelease of
     ‘1.9’, `not' a development pre-release of ‘1.9a’.  Use ‘.dev’
     instead, as in ‘1.9a.dev’, or separate the prerelease tags with a
     number, as in ‘1.9a0dev’.  ‘1.9a.dev’, ‘1.9a0dev’, and even
     ‘1.9.a.dev’ are identical versions from setuptools’ point of view,
     so you can use whatever scheme you prefer.

   * If you want to be certain that your chosen numbering scheme works
     the way you think it will, you can use the
     ‘pkg_resources.parse_version()’ function to compare different
     version numbers:

          >>> from pkg_resources import parse_version
          >>> parse_version("1.9.a.dev") == parse_version("1.9a0dev")
          True
          >>> parse_version("2.1-rc2") < parse_version("2.1")
          True
          >>> parse_version("0.6a9dev-r41475") < parse_version("0.6a9")
          True

Once you’ve decided on a version numbering scheme for your project, you
can have setuptools automatically tag your in-development releases with
various pre- or post-release tags.  See the following sections for more
details:

   * *note Tagging and "Daily Build" or "Snapshot" Releases: 3c.

   * The *note egg_info: 3d. command


File: setuptools.info,  Node: Creating distutils Extensions,  Next: Configuring setup using setup cfg files,  Prev: Specifying Your Project’s Version,  Up: Transition to PEP517

1.1.11 Creating ‘distutils’ Extensions
--------------------------------------

It can be hard to add new commands or setup arguments to the distutils.
But the ‘setuptools’ package makes it a bit easier, by allowing you to
distribute a distutils extension as a separate project, and then have
projects that need the extension just refer to it in their
‘setup_requires’ argument.

With ‘setuptools’, your distutils extension projects can hook in new
commands and ‘setup()’ arguments just by defining “entry points”.  These
are mappings from command or argument names to a specification of where
to import a handler from.  (See the section on *note Advertising
Behavior: 25. above for some more background on entry points.)

* Menu:

* Adding Commands::
* Adding setup() Arguments: Adding setup Arguments.
* Customizing Distribution Options::
* Adding new EGG-INFO Files::
* Adding Support for Revision Control Systems::


File: setuptools.info,  Node: Adding Commands,  Next: Adding setup Arguments,  Up: Creating distutils Extensions

1.1.11.1 Adding Commands
........................

You can add new ‘setup’ commands by defining entry points in the
‘distutils.commands’ group.  For example, if you wanted to add a ‘foo’
command, you might add something like this to your distutils extension
project’s setup script:

     setup(
         # ...
         entry_points={
             "distutils.commands": [
                 "foo = mypackage.some_module:foo",
             ],
         },
     )

(Assuming, of course, that the ‘foo’ class in ‘mypackage.some_module’ is
a ‘setuptools.Command’ subclass.)

Once a project containing such entry points has been activated on
‘sys.path’, (e.g.  by running “install” or “develop” with a
site-packages installation directory) the command(s) will be available
to any ‘setuptools’-based setup scripts.  It is not necessary to use the
‘--command-packages’ option or to monkeypatch the ‘distutils.command’
package to install your commands; ‘setuptools’ automatically adds a
wrapper to the distutils to search for entry points in the active
distributions on ‘sys.path’.  In fact, this is how setuptools’ own
commands are installed: the setuptools project’s setup script defines
entry points for them!


File: setuptools.info,  Node: Adding setup Arguments,  Next: Customizing Distribution Options,  Prev: Adding Commands,  Up: Creating distutils Extensions

1.1.11.2 Adding ‘setup()’ Arguments
...................................

     Warning: Adding arguments to setup is discouraged as such arguments
     are only supported through imperative execution and not supported
     through declarative config.

Sometimes, your commands may need additional arguments to the ‘setup()’
call.  You can enable this by defining entry points in the
‘distutils.setup_keywords’ group.  For example, if you wanted a
‘setup()’ argument called ‘bar_baz’, you might add something like this
to your distutils extension project’s setup script:

     setup(
         # ...
         entry_points={
             "distutils.commands": [
                 "foo = mypackage.some_module:foo",
             ],
             "distutils.setup_keywords": [
                 "bar_baz = mypackage.some_module:validate_bar_baz",
             ],
         },
     )

The idea here is that the entry point defines a function that will be
called to validate the ‘setup()’ argument, if it’s supplied.  The
‘Distribution’ object will have the initial value of the attribute set
to ‘None’, and the validation function will only be called if the
‘setup()’ call sets it to a non-None value.  Here’s an example
validation function:

     def assert_bool(dist, attr, value):
         """Verify that value is True, False, 0, or 1"""
         if bool(value) != value:
             raise DistutilsSetupError(
                 "%r must be a boolean value (got %r)" % (attr,value)
             )

Your function should accept three arguments: the ‘Distribution’ object,
the attribute name, and the attribute value.  It should raise a
‘DistutilsSetupError’ (from the ‘distutils.errors’ module) if the
argument is invalid.  Remember, your function will only be called with
non-None values, and the default value of arguments defined this way is
always None.  So, your commands should always be prepared for the
possibility that the attribute will be ‘None’ when they access it later.

If more than one active distribution defines an entry point for the same
‘setup()’ argument, `all' of them will be called.  This allows multiple
distutils extensions to define a common argument, as long as they agree
on what values of that argument are valid.

Also note that as with commands, it is not necessary to subclass or
monkeypatch the distutils ‘Distribution’ class in order to add your
arguments; it is sufficient to define the entry points in your
extension, as long as any setup script using your extension lists your
project in its ‘setup_requires’ argument.


File: setuptools.info,  Node: Customizing Distribution Options,  Next: Adding new EGG-INFO Files,  Prev: Adding setup Arguments,  Up: Creating distutils Extensions

1.1.11.3 Customizing Distribution Options
.........................................

Plugins may wish to extend or alter the options on a Distribution object
to suit the purposes of that project.  For example, a tool that infers
the ‘Distribution.version’ from SCM-metadata may need to hook into the
option finalization.  To enable this feature, Setuptools offers an entry
point “setuptools.finalize_distribution_options”.  That entry point must
be a callable taking one argument (the Distribution instance).

If the callable has an ‘.order’ property, that value will be used to
determine the order in which the hook is called.  Lower numbers are
called first and the default is zero (0).

Plugins may read, alter, and set properties on the distribution, but
each plugin is encouraged to load the configuration/settings for their
behavior independently.


File: setuptools.info,  Node: Adding new EGG-INFO Files,  Next: Adding Support for Revision Control Systems,  Prev: Customizing Distribution Options,  Up: Creating distutils Extensions

1.1.11.4 Adding new EGG-INFO Files
..................................

Some extensible applications or frameworks may want to allow third
parties to develop plugins with application or framework-specific
metadata included in the plugins’ EGG-INFO directory, for easy access
via the ‘pkg_resources’ metadata API. The easiest way to allow this is
to create a distutils extension to be used from the plugin projects’
setup scripts (via ‘setup_requires’) that defines a new setup keyword,
and then uses that data to write an EGG-INFO file when the ‘egg_info’
command is run.

The ‘egg_info’ command looks for extension points in an
‘egg_info.writers’ group, and calls them to write the files.  Here’s a
simple example of a distutils extension defining a setup argument
‘foo_bar’, which is a list of lines that will be written to
‘foo_bar.txt’ in the EGG-INFO directory of any project that uses the
argument:

     setup(
         # ...
         entry_points={
             "distutils.setup_keywords": [
                 "foo_bar = setuptools.dist:assert_string_list",
             ],
             "egg_info.writers": [
                 "foo_bar.txt = setuptools.command.egg_info:write_arg",
             ],
         },
     )

This simple example makes use of two utility functions defined by
setuptools for its own use: a routine to validate that a setup keyword
is a sequence of strings, and another one that looks up a setup argument
and writes it to a file.  Here’s what the writer utility looks like:

     def write_arg(cmd, basename, filename):
         argname = os.path.splitext(basename)[0]
         value = getattr(cmd.distribution, argname, None)
         if value is not None:
             value = "\n".join(value) + "\n"
         cmd.write_or_delete_file(argname, filename, value)

As you can see, ‘egg_info.writers’ entry points must be a function
taking three arguments: a ‘egg_info’ command instance, the basename of
the file to write (e.g.  ‘foo_bar.txt’), and the actual full filename
that should be written to.

In general, writer functions should honor the command object’s ‘dry_run’
setting when writing files, and use the ‘distutils.log’ object to do any
console output.  The easiest way to conform to this requirement is to
use the ‘cmd’ object’s ‘write_file()’, ‘delete_file()’, and
‘write_or_delete_file()’ methods exclusively for your file operations.
See those methods’ docstrings for more details.


File: setuptools.info,  Node: Adding Support for Revision Control Systems,  Prev: Adding new EGG-INFO Files,  Up: Creating distutils Extensions

1.1.11.5 Adding Support for Revision Control Systems
....................................................

If the files you want to include in the source distribution are tracked
using Git, Mercurial or SVN, you can use the following packages to
achieve that:

   - Git and Mercurial: setuptools_scm(1)

   - SVN: setuptools_svn(2)

If you would like to create a plugin for ‘setuptools’ to find files
tracked by another revision control system, you can do so by adding an
entry point to the ‘setuptools.file_finders’ group.  The entry point
should be a function accepting a single directory name, and should yield
all the filenames within that directory (and any subdirectories thereof)
that are under revision control.

For example, if you were going to create a plugin for a revision control
system called “foobar”, you would write a function something like this:

     def find_files_for_foobar(dirname):
         # loop to yield paths that start with `dirname`

And you would register it in a setup script using something like this:

     entry_points={
         "setuptools.file_finders": [
             "foobar = my_foobar_module:find_files_for_foobar",
         ]
     }

Then, anyone who wants to use your plugin can simply install it, and
their local setuptools installation will be able to find the necessary
files.

It is not necessary to distribute source control plugins with projects
that simply use the other source control system, or to specify the
plugins in ‘setup_requires’.  When you create a source distribution with
the ‘sdist’ command, setuptools automatically records what files were
found in the ‘SOURCES.txt’ file.  That way, recipients of source
distributions don’t need to have revision control at all.  However, if
someone is working on a package by checking out with that system, they
will need the same plugin(s) that the original author is using.

A few important points for writing revision control file finders:

   * Your finder function MUST return relative paths, created by
     appending to the passed-in directory name.  Absolute paths are NOT
     allowed, nor are relative paths that reference a parent directory
     of the passed-in directory.

   * Your finder function MUST accept an empty string as the directory
     name, meaning the current directory.  You MUST NOT convert this to
     a dot; just yield relative paths.  So, yielding a subdirectory
     named ‘some/dir’ under the current directory should NOT be rendered
     as ‘./some/dir’ or ‘/somewhere/some/dir’, but `always' as simply
     ‘some/dir’

   * Your finder function SHOULD NOT raise any errors, and SHOULD deal
     gracefully with the absence of needed programs (i.e., ones
     belonging to the revision control system itself.  It `may',
     however, use ‘distutils.log.warn()’ to inform the user of the
     missing program(s).

   ---------- Footnotes ----------

   (1) https://pypi.org/project/setuptools_scm/

   (2) https://pypi.org/project/setuptools_svn/


File: setuptools.info,  Node: Configuring setup using setup cfg files,  Next: New and Changed setup Keywords,  Prev: Creating distutils Extensions,  Up: Transition to PEP517

1.1.12 Configuring setup() using setup.cfg files
------------------------------------------------

     Note: New in 30.3.0 (8 Dec 2016).

     Important: If compatibility with legacy builds (i.e.  those not
     using the PEP 517(1) build API) is desired, a ‘setup.py’ file
     containing a ‘setup()’ function call is still required even if your
     configuration resides in ‘setup.cfg’.

‘Setuptools’ allows using configuration files (usually ‘setup.cfg’) to
define a package’s metadata and other options that are normally supplied
to the ‘setup()’ function (declarative config).

This approach not only allows automation scenarios but also reduces
boilerplate code in some cases.

     Note: This implementation has limited compatibility with the
     distutils2-like ‘setup.cfg’ sections used by the ‘pbr’ and ‘d2to1’
     packages.

     Namely: only metadata-related keys from ‘metadata’ section are
     supported (except for ‘description-file’); keys from ‘files’,
     ‘entry_points’ and ‘backwards_compat’ are not supported.

     [metadata]
     name = my_package
     version = attr: src.VERSION
     description = My package description
     long_description = file: README.rst, CHANGELOG.rst, LICENSE.rst
     keywords = one, two
     license = BSD 3-Clause License
     classifiers =
         Framework :: Django
         License :: OSI Approved :: BSD License
         Programming Language :: Python :: 3
         Programming Language :: Python :: 3.5

     [options]
     zip_safe = False
     include_package_data = True
     packages = find:
     scripts =
         bin/first.py
         bin/second.py
     install_requires =
         requests
         importlib; python_version == "2.6"

     [options.package_data]
     * = *.txt, *.rst
     hello = *.msg

     [options.extras_require]
     pdf = ReportLab>=1.2; RXP
     rest = docutils>=0.3; pack ==1.1, ==1.3

     [options.packages.find]
     exclude =
         src.subpackage1
         src.subpackage2

     [options.data_files]
     /etc/my_package =
         site.d/00_default.conf
         host.d/00_default.conf
     data = data/img/logo.png, data/svg/icon.svg

Metadata and options are set in the config sections of the same name.

   * Keys are the same as the keyword arguments one provides to the
     ‘setup()’ function.

   * Complex values can be written comma-separated or placed one per
     line in `dangling' config values.  The following are equivalent:

          [metadata]
          keywords = one, two

          [metadata]
          keywords =
              one
              two

   * In some cases, complex values can be provided in dedicated
     subsections for clarity.

   * Some keys allow ‘file:’, ‘attr:’, ‘find:’, and ‘find_namespace:’
     directives in order to cover common usecases.

   * Unknown keys are ignored.

* Menu:

* Using a src/ layout::
* Specifying values::

   ---------- Footnotes ----------

   (1) https://www.python.org/dev/peps/pep-0517


File: setuptools.info,  Node: Using a src/ layout,  Next: Specifying values,  Up: Configuring setup using setup cfg files

1.1.12.1 Using a ‘src/’ layout
..............................

One commonly used package configuration has all the module source code
in a subdirectory (often called the ‘src/’ layout), like this:

     ├── src
     │   └── mypackage
     │       ├── __init__.py
     │       └── mod1.py
     ├── setup.py
     └── setup.cfg

You can set up your ‘setup.cfg’ to automatically find all your packages
in the subdirectory like this:

     # This example contains just the necessary options for a src-layout, set up
     # the rest of the file as described above.

     [options]
     package_dir=
         =src
     packages=find:

     [options.packages.find]
     where=src


File: setuptools.info,  Node: Specifying values,  Prev: Using a src/ layout,  Up: Configuring setup using setup cfg files

1.1.12.2 Specifying values
..........................

Some values are treated as simple strings, some allow more logic.

Type names used below:

   * ‘str’ - simple string

   * ‘list-comma’ - dangling list or string of comma-separated values

   * ‘list-semi’ - dangling list or string of semicolon-separated values

   * ‘bool’ - ‘True’ is 1, yes, true

   * ‘dict’ - list-comma where keys are separated from values by ‘=’

   * ‘section’ - values are read from a dedicated (sub)section

Special directives:

   * ‘attr:’ - Value is read from a module attribute.  ‘attr:’ supports
     callables and iterables; unsupported types are cast using ‘str()’.

     In order to support the common case of a literal value assigned to
     a variable in a module containing (directly or indirectly)
     third-party imports, ‘attr:’ first tries to read the value from the
     module by examining the module’s AST. If that fails, ‘attr:’ falls
     back to importing the module.

   * ‘file:’ - Value is read from a list of files and then concatenated

     Note: The ‘file:’ directive is sandboxed and won’t reach anything
     outside the directory containing ‘setup.py’.

* Menu:

* Metadata::
* Options::


File: setuptools.info,  Node: Metadata,  Next: Options,  Up: Specifying values

1.1.12.3 Metadata
.................

     Note: The aliases given below are supported for compatibility
     reasons, but their use is not advised.

Key                                Aliases               Type                  Minimum Version     Notes
                                                                                                   
-------------------------------------------------------------------------------------------------------------
                                                                                                   
name                                                     str
                                                         
                                                                                                   
version                                                  attr:, file:, str     39.2.0                1. 
                                                                               
                                                                                                   
url                                home-page             str
                                                         
                                                                                                   
download_url                       download-url          str
                                                         
                                                                                                   
project_urls                                             dict                  38.3.0
                                                                               
                                                                                                   
author                                                   str
                                                         
                                                                                                   
author_email                       author-email          str
                                                         
                                                                                                   
maintainer                                               str
                                                         
                                                                                                   
maintainer_email                   maintainer-email      str
                                                         
                                                                                                   
classifiers                        classifier            file:, list-comma
                                                         
                                                                                                   
license                                                  str
                                                         
                                                                                                   
license_file                                             str
                                                         
                                                                                                   
license_files                                            list-comma
                                                         
                                                                                                   
description                        summary               file:, str
                                                         
                                                                                                   
long_description                   long-description      file:, str
                                                         
                                                                                                   
long_description_content_type                            str                   38.6.0
                                                                               
                                                                                                   
keywords                                                 list-comma
                                                         
                                                                                                   
platforms                          platform              list-comma
                                                         
                                                                                                   
provides                                                 list-comma
                                                         
                                                                                                   
requires                                                 list-comma
                                                         
                                                                                                   
obsoletes                                                list-comma
                                                         

     Note: A version loaded using the ‘file:’ directive must comply with
     PEP 440.  It is easy to accidentally put something other than a
     valid version string in such a file, so validation is stricter in
     this case.

Notes: 1.  The ‘version’ file attribute has only been supported since
39.2.0.


File: setuptools.info,  Node: Options,  Prev: Metadata,  Up: Specifying values

1.1.12.4 Options
................

Key                         Type                                    Minimum Version     Notes
                                                                                        
--------------------------------------------------------------------------------------------------
                                                                                        
zip_safe                    bool
                            
                                                                                        
setup_requires              list-semi
                            
                                                                                        
install_requires            list-semi
                            
                                                                                        
extras_require              section
                            
                                                                                        
python_requires             str
                            
                                                                                        
entry_points                file:, section
                            
                                                                                        
use_2to3                    bool
                            
                                                                                        
use_2to3_fixers             list-comma
                            
                                                                                        
use_2to3_exclude_fixers     list-comma
                            
                                                                                        
convert_2to3_doctests       list-comma
                            
                                                                                        
scripts                     list-comma
                            
                                                                                        
eager_resources             list-comma
                            
                                                                                        
dependency_links            list-comma
                            
                                                                                        
tests_require               list-semi
                            
                                                                                        
include_package_data        bool
                            
                                                                                        
packages                    find:, find_namespace:, list-comma
                            
                                                                                        
package_dir                 dict
                            
                                                                                        
package_data                section                                                       1. 
                            
                                                                                        
exclude_package_data        section
                            
                                                                                        
namespace_packages          list-comma
                            
                                                                                        
py_modules                  list-comma
                            
                                                                                        
data_files                  dict                                    40.6.0
                                                                    

     Note: `packages' - The ‘find:’ and ‘find_namespace:’ directive can
     be further configured in a dedicated subsection
     ‘options.packages.find’.  This subsection accepts the same keys as
     the ‘setuptools.find_packages’ and the
     ‘setuptools.find_namespace_packages’ function: ‘where’, ‘include’,
     and ‘exclude’.

     `find_namespace directive' - The ‘find_namespace:’ directive is
     supported since Python >=3.3.

Notes: 1.  In the ‘package_data’ section, a key named with a single
asterisk (‘*’) refers to all packages, in lieu of the empty string used
in ‘setup.py’.


File: setuptools.info,  Node: New and Changed setup Keywords,  Next: Command Reference,  Prev: Configuring setup using setup cfg files,  Up: Transition to PEP517

1.1.13 New and Changed ‘setup()’ Keywords
-----------------------------------------

The following keyword arguments to ‘setup()’ are added or changed by
‘setuptools’.  All of them are optional; you do not have to supply them
unless you need the associated ‘setuptools’ feature.

‘include_package_data’

     If set to ‘True’, this tells ‘setuptools’ to automatically include
     any data files it finds inside your package directories that are
     specified by your ‘MANIFEST.in’ file.  For more information, see
     the section on *note Including Data Files: 12.

‘exclude_package_data’

     A dictionary mapping package names to lists of glob patterns that
     should be `excluded' from your package directories.  You can use
     this to trim back any excess files included by
     ‘include_package_data’.  For a complete description and examples,
     see the section on *note Including Data Files: 12.

‘package_data’

     A dictionary mapping package names to lists of glob patterns.  For
     a complete description and examples, see the section on *note
     Including Data Files: 12.  You do not need to use this option if
     you are using ‘include_package_data’, unless you need to add e.g.
     files that are generated by your setup script and build process.
     (And are therefore not in source control or are files that you
     don’t want to include in your source distribution.)

‘zip_safe’

     A boolean (True or False) flag specifying whether the project can
     be safely installed and run from a zip file.  If this argument is
     not supplied, the ‘bdist_egg’ command will have to analyze all of
     your project’s contents for possible problems each time it builds
     an egg.

‘install_requires’

     A string or list of strings specifying what other distributions
     need to be installed when this one is.  See the section on *note
     Declaring required dependency: 2b. for details and examples of the
     format of this argument.

‘entry_points’

     A dictionary mapping entry point group names to strings or lists of
     strings defining the entry points.  Entry points are used to
     support dynamic discovery of services or plugins provided by a
     project.  See *note Advertising Behavior: 25. for details and
     examples of the format of this argument.  In addition, this keyword
     is used to support *note Automatic Script Creation: 21.

‘extras_require’

     A dictionary mapping names of “extras” (optional features of your
     project) to strings or lists of strings specifying what other
     distributions must be installed to support those features.  See the
     section on *note Declaring required dependency: 2b. for details and
     examples of the format of this argument.

‘python_requires’

     A string corresponding to a version specifier (as defined in PEP
     440) for the Python version, used to specify the Requires-Python
     defined in PEP 345.

‘setup_requires’

     A string or list of strings specifying what other distributions
     need to be present in order for the `setup script' to run.
     ‘setuptools’ will attempt to obtain these (using pip if available)
     before processing the rest of the setup script or commands.  This
     argument is needed if you are using distutils extensions as part of
     your build process; for example, extensions that process setup()
     arguments and turn them into EGG-INFO metadata files.

     (Note: projects listed in ‘setup_requires’ will NOT be
     automatically installed on the system where the setup script is
     being run.  They are simply downloaded to the ./.eggs directory if
     they’re not locally available already.  If you want them to be
     installed, as well as being available when the setup script is run,
     you should add them to ‘install_requires’ `and' ‘setup_requires’.)

‘dependency_links’

     A list of strings naming URLs to be searched when satisfying
     dependencies.  These links will be used if needed to install
     packages specified by ‘setup_requires’ or ‘tests_require’.  They
     will also be written into the egg’s metadata for use during install
     by tools that support them.

‘namespace_packages’

     A list of strings naming the project’s “namespace packages”.  A
     namespace package is a package that may be split across multiple
     project distributions.  For example, Zope 3’s ‘zope’ package is a
     namespace package, because subpackages like ‘zope.interface’ and
     ‘zope.publisher’ may be distributed separately.  The egg runtime
     system can automatically merge such subpackages into a single
     parent package at runtime, as long as you declare them in each
     project that contains any subpackages of the namespace package, and
     as long as the namespace package’s ‘__init__.py’ does not contain
     any code other than a namespace declaration.  See the section below
     on *note Using find_namespace; or find_namespace_packages: 1c. for
     more information.

‘test_suite’

     A string naming a ‘unittest.TestCase’ subclass (or a package or
     module containing one or more of them, or a method of such a
     subclass), or naming a function that can be called with no
     arguments and returns a ‘unittest.TestSuite’.  If the named suite
     is a module, and the module has an ‘additional_tests()’ function,
     it is called and the results are added to the tests to be run.  If
     the named suite is a package, any submodules and subpackages are
     recursively added to the overall test suite.

     Specifying this argument enables use of the *note test: 56. command
     to run the specified test suite, e.g.  via ‘setup.py test’.  See
     the section on the *note test: 56. command below for more details.

     New in 41.5.0: Deprecated the test command.

‘tests_require’

     If your project’s tests need one or more additional packages
     besides those needed to install it, you can use this option to
     specify them.  It should be a string or list of strings specifying
     what other distributions need to be present for the package’s tests
     to run.  When you run the ‘test’ command, ‘setuptools’ will attempt
     to obtain these (using pip if available).  Note that these required
     projects will `not' be installed on the system where the tests are
     run, but only downloaded to the project’s setup directory if
     they’re not already installed locally.

     New in 41.5.0: Deprecated the test command.

‘test_loader’

     If you would like to use a different way of finding tests to run
     than what setuptools normally uses, you can specify a module name
     and class name in this argument.  The named class must be
     instantiable with no arguments, and its instances must support the
     ‘loadTestsFromNames()’ method as defined in the Python ‘unittest’
     module’s ‘TestLoader’ class.  Setuptools will pass only one test
     “name” in the ‘names’ argument: the value supplied for the
     ‘test_suite’ argument.  The loader you specify may interpret this
     string in any way it likes, as there are no restrictions on what
     may be contained in a ‘test_suite’ string.

     The module name and class name must be separated by a ‘:’.  The
     default value of this argument is
     ‘"setuptools.command.test:ScanningLoader"’.  If you want to use the
     default ‘unittest’ behavior, you can specify
     ‘"unittest:TestLoader"’ as your ‘test_loader’ argument instead.
     This will prevent automatic scanning of submodules and subpackages.

     The module and class you specify here may be contained in another
     package, as long as you use the ‘tests_require’ option to ensure
     that the package containing the loader class is available when the
     ‘test’ command is run.

     New in 41.5.0: Deprecated the test command.

‘eager_resources’

     A list of strings naming resources that should be extracted
     together, if any of them is needed, or if any C extensions included
     in the project are imported.  This argument is only useful if the
     project will be installed as a zipfile, and there is a need to have
     all of the listed resources be extracted to the filesystem `as a
     unit'.  Resources listed here should be “/”-separated paths,
     relative to the source root, so to list a resource ‘foo.png’ in
     package ‘bar.baz’, you would include the string ‘bar/baz/foo.png’
     in this argument.

     If you only need to obtain resources one at a time, or you don’t
     have any C extensions that access other files in the project (such
     as data files or shared libraries), you probably do NOT need this
     argument and shouldn’t mess with it.  For more details on how this
     argument works, see the section below on *note Automatic Resource
     Extraction: 58.

‘use_2to3’

     Convert the source code from Python 2 to Python 3 with 2to3 during
     the build process.  See *note Supporting both Python 2 and Python 3
     with Setuptools: 59. for more details.

‘convert_2to3_doctests’

     List of doctest source files that need to be converted with 2to3.
     See *note Supporting both Python 2 and Python 3 with Setuptools:
     59. for more details.

‘use_2to3_fixers’

     A list of modules to search for additional fixers to be used during
     the 2to3 conversion.  See *note Supporting both Python 2 and Python
     3 with Setuptools: 59. for more details.

‘project_urls’

     An arbitrary map of URL names to hyperlinks, allowing more
     extensible documentation of where various resources can be found
     than the simple ‘url’ and ‘download_url’ options provide.


File: setuptools.info,  Node: Command Reference,  Next: Using setuptools to package and distribute your project,  Prev: New and Changed setup Keywords,  Up: Transition to PEP517

1.1.14 Command Reference
------------------------

* Menu:

* alias - Define shortcuts for commonly used commands::
* bdist_egg - Create a Python Egg for the project::
* develop - Deploy the project source in “Development Mode”::
* egg_info - Create egg metadata and set build tags::
* rotate - Delete outdated distribution files::
* saveopts - Save used options to a configuration file::
* setopt - Set a distutils or setuptools option in a config file::
* test - Build package and run a unittest suite::
* upload - Upload source and/or egg distributions to PyPI::


File: setuptools.info,  Node: alias - Define shortcuts for commonly used commands,  Next: bdist_egg - Create a Python Egg for the project,  Up: Command Reference

1.1.14.1 ‘alias’ - Define shortcuts for commonly used commands
..............................................................

Sometimes, you need to use the same commands over and over, but you
can’t necessarily set them as defaults.  For example, if you produce
both development snapshot releases and “stable” releases of a project,
you may want to put the distributions in different places, or use
different ‘egg_info’ tagging options, etc.  In these cases, it doesn’t
make sense to set the options in a distutils configuration file, because
the values of the options changed based on what you’re trying to do.

Setuptools therefore allows you to define “aliases” - shortcut names for
an arbitrary string of commands and options, using ‘setup.py alias
aliasname expansion’, where aliasname is the name of the new alias, and
the remainder of the command line supplies its expansion.  For example,
this command defines a sitewide alias called “daily”, that sets various
‘egg_info’ tagging options:

     setup.py alias --global-config daily egg_info --tag-build=development

Once the alias is defined, it can then be used with other setup
commands, e.g.:

     setup.py daily bdist_egg        # generate a daily-build .egg file
     setup.py daily sdist            # generate a daily-build source distro
     setup.py daily sdist bdist_egg  # generate both

The above commands are interpreted as if the word ‘daily’ were replaced
with ‘egg_info --tag-build=development’.

Note that setuptools will expand each alias `at most once' in a given
command line.  This serves two purposes.  First, if you accidentally
create an alias loop, it will have no effect; you’ll instead get an
error message about an unknown command.  Second, it allows you to define
an alias for a command, that uses that command.  For example, this
(project-local) alias:

     setup.py alias bdist_egg bdist_egg rotate -k1 -m.egg

redefines the ‘bdist_egg’ command so that it always runs the ‘rotate’
command afterwards to delete all but the newest egg file.  It doesn’t
loop indefinitely on ‘bdist_egg’ because the alias is only expanded once
when used.

You can remove a defined alias with the ‘--remove’ (or ‘-r’) option,
e.g.:

     setup.py alias --global-config --remove daily

would delete the “daily” alias we defined above.

Aliases can be defined on a project-specific, per-user, or sitewide
basis.  The default is to define or remove a project-specific alias, but
you can use any of the *note configuration file options: 5d. (listed
under the *note saveopts: 5e. command, below) to determine which
distutils configuration file an aliases will be added to (or removed
from).

Note that if you omit the “expansion” argument to the ‘alias’ command,
you’ll get output showing that alias’ current definition (and what
configuration file it’s defined in).  If you omit the alias name as
well, you’ll get a listing of all current aliases along with their
configuration file locations.


File: setuptools.info,  Node: bdist_egg - Create a Python Egg for the project,  Next: develop - Deploy the project source in “Development Mode”,  Prev: alias - Define shortcuts for commonly used commands,  Up: Command Reference

1.1.14.2 ‘bdist_egg’ - Create a Python Egg for the project
..........................................................

     Warning: `eggs' are deprecated in favor of wheels, and not
     supported by pip.

This command generates a Python Egg (‘.egg’ file) for the project.
Python Eggs are the preferred binary distribution format for
EasyInstall, because they are cross-platform (for “pure” packages),
directly importable, and contain project metadata including scripts and
information about the project’s dependencies.  They can be simply
downloaded and added to ‘sys.path’ directly, or they can be placed in a
directory on ‘sys.path’ and then automatically discovered by the egg
runtime system.

This command runs the *note egg_info: 3d. command (if it hasn’t already
run) to update the project’s metadata (‘.egg-info’) directory.  If you
have added any extra metadata files to the ‘.egg-info’ directory, those
files will be included in the new egg file’s metadata directory, for use
by the egg runtime system or by any applications or frameworks that use
that metadata.

You won’t usually need to specify any special options for this command;
just use ‘bdist_egg’ and you’re done.  But there are a few options that
may be occasionally useful:

‘--dist-dir=DIR, -d DIR’

     Set the directory where the ‘.egg’ file will be placed.  If you
     don’t supply this, then the ‘--dist-dir’ setting of the ‘bdist’
     command will be used, which is usually a directory named ‘dist’ in
     the project directory.

‘--plat-name=PLATFORM, -p PLATFORM’

     Set the platform name string that will be embedded in the egg’s
     filename (assuming the egg contains C extensions).  This can be
     used to override the distutils default platform name with something
     more meaningful.  Keep in mind, however, that the egg runtime
     system expects to see eggs with distutils platform names, so it may
     ignore or reject eggs with non-standard platform names.  Similarly,
     the EasyInstall program may ignore them when searching web pages
     for download links.  However, if you are cross-compiling or doing
     some other unusual things, you might find a use for this option.

‘--exclude-source-files’

     Don’t include any modules’ ‘.py’ files in the egg, just compiled
     Python, C, and data files.  (Note that this doesn’t affect any
     ‘.py’ files in the EGG-INFO directory or its subdirectories, since
     for example there may be scripts with a ‘.py’ extension which must
     still be retained.)  We don’t recommend that you use this option
     except for packages that are being bundled for proprietary end-user
     applications, or for “embedded” scenarios where space is at an
     absolute premium.  On the other hand, if your package is going to
     be installed and used in compressed form, you might as well exclude
     the source because Python’s ‘traceback’ module doesn’t currently
     understand how to display zipped source code anyway, or how to deal
     with files that are in a different place from where their code was
     compiled.

There are also some options you will probably never need, but which are
there because they were copied from similar ‘bdist’ commands used as an
example for creating this one.  They may be useful for testing and
debugging, however, which is why we kept them:

‘--keep-temp, -k’

     Keep the contents of the ‘--bdist-dir’ tree around after creating
     the ‘.egg’ file.

‘--bdist-dir=DIR, -b DIR’

     Set the temporary directory for creating the distribution.  The
     entire contents of this directory are zipped to create the ‘.egg’
     file, after running various installation commands to copy the
     package’s modules, data, and extensions here.

‘--skip-build’

     Skip doing any “build” commands; just go straight to the
     install-and-compress phases.


File: setuptools.info,  Node: develop - Deploy the project source in “Development Mode”,  Next: egg_info - Create egg metadata and set build tags,  Prev: bdist_egg - Create a Python Egg for the project,  Up: Command Reference

1.1.14.3 ‘develop’ - Deploy the project source in “Development Mode”
....................................................................

This command allows you to deploy your project’s source for use in one
or more “staging areas” where it will be available for importing.  This
deployment is done in such a way that changes to the project source are
immediately available in the staging area(s), without needing to run a
build or install step after each change.

The ‘develop’ command works by creating an ‘.egg-link’ file (named for
the project) in the given staging area.  If the staging area is Python’s
‘site-packages’ directory, it also updates an ‘easy-install.pth’ file so
that the project is on ‘sys.path’ by default for all programs run using
that Python installation.

The ‘develop’ command also installs wrapper scripts in the staging area
(or a separate directory, as specified) that will ensure the project’s
dependencies are available on ‘sys.path’ before running the project’s
source scripts.  And, it ensures that any missing project dependencies
are available in the staging area, by downloading and installing them if
necessary.

Last, but not least, the ‘develop’ command invokes the ‘build_ext -i’
command to ensure any C extensions in the project have been built and
are up-to-date, and the ‘egg_info’ command to ensure the project’s
metadata is updated (so that the runtime and wrappers know what the
project’s dependencies are).  If you make any changes to the project’s
setup script or C extensions, you should rerun the ‘develop’ command
against all relevant staging areas to keep the project’s scripts,
metadata and extensions up-to-date.  Most other kinds of changes to your
project should not require any build operations or rerunning ‘develop’,
but keep in mind that even minor changes to the setup script (e.g.
changing an entry point definition) require you to re-run the ‘develop’
or ‘test’ commands to keep the distribution updated.

Here are some of the options that the ‘develop’ command accepts.  Note
that they affect the project’s dependencies as well as the project
itself, so if you have dependencies that need to be installed and you
use ‘--exclude-scripts’ (for example), the dependencies’ scripts will
not be installed either!  For this reason, you may want to use pip to
install the project’s dependencies before using the ‘develop’ command,
if you need finer control over the installation options for
dependencies.

‘--uninstall, -u’

     Un-deploy the current project.  You may use the ‘--install-dir’ or
     ‘-d’ option to designate the staging area.  The created ‘.egg-link’
     file will be removed, if present and it is still pointing to the
     project directory.  The project directory will be removed from
     ‘easy-install.pth’ if the staging area is Python’s ‘site-packages’
     directory.

     Note that this option currently does `not' uninstall script
     wrappers!  You must uninstall them yourself, or overwrite them by
     using pip to install a different version of the package.  You can
     also avoid installing script wrappers in the first place, if you
     use the ‘--exclude-scripts’ (aka ‘-x’) option when you run
     ‘develop’ to deploy the project.

‘--multi-version, -m’

     “Multi-version” mode.  Specifying this option prevents ‘develop’
     from adding an ‘easy-install.pth’ entry for the project(s) being
     deployed, and if an entry for any version of a project already
     exists, the entry will be removed upon successful deployment.  In
     multi-version mode, no specific version of the package is available
     for importing, unless you use ‘pkg_resources.require()’ to put it
     on ‘sys.path’, or you are running a wrapper script generated by
     ‘setuptools’.  (In which case the wrapper script calls ‘require()’
     for you.)

     Note that if you install to a directory other than ‘site-packages’,
     this option is automatically in effect, because ‘.pth’ files can
     only be used in ‘site-packages’ (at least in Python 2.3 and 2.4).
     So, if you use the ‘--install-dir’ or ‘-d’ option (or they are set
     via configuration file(s)) your project and its dependencies will
     be deployed in multi- version mode.

‘--install-dir=DIR, -d DIR’

     Set the installation directory (staging area).  If this option is
     not directly specified on the command line or in a distutils
     configuration file, the distutils default installation location is
     used.  Normally, this will be the ‘site-packages’ directory, but if
     you are using distutils configuration files, setting things like
     ‘prefix’ or ‘install_lib’, then those settings are taken into
     account when computing the default staging area.

‘--script-dir=DIR, -s DIR’

     Set the script installation directory.  If you don’t supply this
     option (via the command line or a configuration file), but you
     `have' supplied an ‘--install-dir’ (via command line or config
     file), then this option defaults to the same directory, so that the
     scripts will be able to find their associated package installation.
     Otherwise, this setting defaults to the location where the
     distutils would normally install scripts, taking any distutils
     configuration file settings into account.

‘--exclude-scripts, -x’

     Don’t deploy script wrappers.  This is useful if you don’t want to
     disturb existing versions of the scripts in the staging area.

‘--always-copy, -a’

     Copy all needed distributions to the staging area, even if they are
     already present in another directory on ‘sys.path’.  By default, if
     a requirement can be met using a distribution that is already
     available in a directory on ‘sys.path’, it will not be copied to
     the staging area.

‘--egg-path=DIR’

     Force the generated ‘.egg-link’ file to use a specified relative
     path to the source directory.  This can be useful in circumstances
     where your installation directory is being shared by code running
     under multiple platforms (e.g.  Mac and Windows) which have
     different absolute locations for the code under development, but
     the same `relative' locations with respect to the installation
     directory.  If you use this option when installing, you must supply
     the same relative path when uninstalling.

In addition to the above options, the ‘develop’ command also accepts all
of the same options accepted by ‘easy_install’.  If you’ve configured
any ‘easy_install’ settings in your ‘setup.cfg’ (or other distutils
config files), the ‘develop’ command will use them as defaults, unless
you override them in a ‘[develop]’ section or on the command line.


File: setuptools.info,  Node: egg_info - Create egg metadata and set build tags,  Next: rotate - Delete outdated distribution files,  Prev: develop - Deploy the project source in “Development Mode”,  Up: Command Reference

1.1.14.4 ‘egg_info’ - Create egg metadata and set build tags
............................................................

This command performs two operations: it updates a project’s ‘.egg-info’
metadata directory (used by the ‘bdist_egg’, ‘develop’, and ‘test’
commands), and it allows you to temporarily change a project’s version
string, to support “daily builds” or “snapshot” releases.  It is run
automatically by the ‘sdist’, ‘bdist_egg’, ‘develop’, and ‘test’
commands in order to update the project’s metadata, but you can also
specify it explicitly in order to temporarily change the project’s
version string while executing other commands.  (It also generates the
‘.egg-info/SOURCES.txt’ manifest file, which is used when you are
building source distributions.)

In addition to writing the core egg metadata defined by ‘setuptools’ and
required by ‘pkg_resources’, this command can be extended to write other
metadata files as well, by defining entry points in the
‘egg_info.writers’ group.  See the section on *note Adding new EGG-INFO
Files: 4b. below for more details.  Note that using additional metadata
writers may require you to include a ‘setup_requires’ argument to
‘setup()’ in order to ensure that the desired writers are available on
‘sys.path’.

* Menu:

* Release Tagging Options::
* Other egg_info Options::
* egg_info Examples::


File: setuptools.info,  Node: Release Tagging Options,  Next: Other egg_info Options,  Up: egg_info - Create egg metadata and set build tags

1.1.14.5 Release Tagging Options
................................

The following options can be used to modify the project’s version string
for all remaining commands on the setup command line.  The options are
processed in the order shown, so if you use more than one, the requested
tags will be added in the following order:

‘--tag-build=NAME, -b NAME’

     Append NAME to the project’s version string.  Due to the way
     setuptools processes “pre-release” version suffixes beginning with
     the letters “a” through “e” (like “alpha”, “beta”, and
     “candidate”), you will usually want to use a tag like “.build” or
     “.dev”, as this will cause the version number to be considered
     `lower' than the project’s default version.  (If you want to make
     the version number `higher' than the default version, you can
     always leave off –tag-build and then use one or both of the
     following options.)

     If you have a default build tag set in your ‘setup.cfg’, you can
     suppress it on the command line using ‘-b ""’ or ‘--tag-build=""’
     as an argument to the ‘egg_info’ command.

‘--tag-date, -d’

     Add a date stamp of the form “-YYYYMMDD” (e.g.  “-20050528”) to the
     project’s version number.

‘--no-date, -D’

     Don’t include a date stamp in the version number.  This option is
     included so you can override a default setting in ‘setup.cfg’.

(Note: Because these options modify the version number used for source
and binary distributions of your project, you should first make sure
that you know how the resulting version numbers will be interpreted by
automated tools like pip.  See the section above on *note Specifying
Your Project’s Version: 3e. for an explanation of pre- and post-release
tags, as well as tips on how to choose and verify a versioning scheme
for your project.)

For advanced uses, there is one other option that can be set, to change
the location of the project’s ‘.egg-info’ directory.  Commands that need
to find the project’s source directory or metadata should get it from
this setting:


File: setuptools.info,  Node: Other egg_info Options,  Next: egg_info Examples,  Prev: Release Tagging Options,  Up: egg_info - Create egg metadata and set build tags

1.1.14.6 Other ‘egg_info’ Options
.................................

‘--egg-base=SOURCEDIR, -e SOURCEDIR’

     Specify the directory that should contain the .egg-info directory.
     This should normally be the root of your project’s source tree
     (which is not necessarily the same as your project directory; some
     projects use a ‘src’ or ‘lib’ subdirectory as the source root).
     You should not normally need to specify this directory, as it is
     normally determined from the ‘package_dir’ argument to the
     ‘setup()’ function, if any.  If there is no ‘package_dir’ set, this
     option defaults to the current directory.


File: setuptools.info,  Node: egg_info Examples,  Prev: Other egg_info Options,  Up: egg_info - Create egg metadata and set build tags

1.1.14.7 ‘egg_info’ Examples
............................

Creating a dated “nightly build” snapshot egg:

     setup.py egg_info --tag-date --tag-build=DEV bdist_egg

Creating a release with no version tags, even if some default tags are
specified in ‘setup.cfg’:

     setup.py egg_info -RDb "" sdist bdist_egg

(Notice that ‘egg_info’ must always appear on the command line `before'
any commands that you want the version changes to apply to.)


File: setuptools.info,  Node: rotate - Delete outdated distribution files,  Next: saveopts - Save used options to a configuration file,  Prev: egg_info - Create egg metadata and set build tags,  Up: Command Reference

1.1.14.8 ‘rotate’ - Delete outdated distribution files
......................................................

As you develop new versions of your project, your distribution (‘dist’)
directory will gradually fill up with older source and/or binary
distribution files.  The ‘rotate’ command lets you automatically clean
these up, keeping only the N most-recently modified files matching a
given pattern.

‘--match=PATTERNLIST, -m PATTERNLIST’

     Comma-separated list of glob patterns to match.  This option is
     `required'.  The project name and ‘-*’ is prepended to the supplied
     patterns, in order to match only distributions belonging to the
     current project (in case you have a shared distribution directory
     for multiple projects).  Typically, you will use a glob pattern
     like ‘.zip’ or ‘.egg’ to match files of the specified type.  Note
     that each supplied pattern is treated as a distinct group of files
     for purposes of selecting files to delete.

‘--keep=COUNT, -k COUNT’

     Number of matching distributions to keep.  For each group of files
     identified by a pattern specified with the ‘--match’ option, delete
     all but the COUNT most-recently-modified files in that group.  This
     option is `required'.

‘--dist-dir=DIR, -d DIR’

     Directory where the distributions are.  This defaults to the value
     of the ‘bdist’ command’s ‘--dist-dir’ option, which will usually be
     the project’s ‘dist’ subdirectory.

`Example 1': Delete all .tar.gz files from the distribution directory,
except for the 3 most recently modified ones:

     setup.py rotate --match=.tar.gz --keep=3

`Example 2': Delete all Python 2.3 or Python 2.4 eggs from the
distribution directory, except the most recently modified one for each
Python version:

     setup.py rotate --match=-py2.3*.egg,-py2.4*.egg --keep=1


File: setuptools.info,  Node: saveopts - Save used options to a configuration file,  Next: setopt - Set a distutils or setuptools option in a config file,  Prev: rotate - Delete outdated distribution files,  Up: Command Reference

1.1.14.9 ‘saveopts’ - Save used options to a configuration file
...............................................................

Finding and editing ‘distutils’ configuration files can be a pain,
especially since you also have to translate the configuration options
from command-line form to the proper configuration file format.  You can
avoid these hassles by using the ‘saveopts’ command.  Just add it to the
command line to save the options you used.  For example, this command
builds the project using the ‘mingw32’ C compiler, then saves the
–compiler setting as the default for future builds (even those run
implicitly by the ‘install’ command):

     setup.py build --compiler=mingw32 saveopts

The ‘saveopts’ command saves all options for every command specified on
the command line to the project’s local ‘setup.cfg’ file, unless you use
one of the *note configuration file options: 5d. to change where the
options are saved.  For example, this command does the same as above,
but saves the compiler setting to the site-wide (global) distutils
configuration:

     setup.py build --compiler=mingw32 saveopts -g

Note that it doesn’t matter where you place the ‘saveopts’ command on
the command line; it will still save all the options specified for all
commands.  For example, this is another valid way to spell the last
example:

     setup.py saveopts -g build --compiler=mingw32

Note, however, that all of the commands specified are always run,
regardless of where ‘saveopts’ is placed on the command line.

* Menu:

* Configuration File Options::


File: setuptools.info,  Node: Configuration File Options,  Up: saveopts - Save used options to a configuration file

1.1.14.10 Configuration File Options
....................................

Normally, settings such as options and aliases are saved to the
project’s local ‘setup.cfg’ file.  But you can override this and save
them to the global or per-user configuration files, or to a
manually-specified filename.

‘--global-config, -g’

     Save settings to the global ‘distutils.cfg’ file inside the
     ‘distutils’ package directory.  You must have write access to that
     directory to use this option.  You also can’t combine this option
     with ‘-u’ or ‘-f’.

‘--user-config, -u’

     Save settings to the current user’s ‘~/.pydistutils.cfg’ (POSIX) or
     ‘$HOME/pydistutils.cfg’ (Windows) file.  You can’t combine this
     option with ‘-g’ or ‘-f’.

‘--filename=FILENAME, -f FILENAME’

     Save settings to the specified configuration file to use.  You
     can’t combine this option with ‘-g’ or ‘-u’.  Note that if you
     specify a non-standard filename, the ‘distutils’ and ‘setuptools’
     will not use the file’s contents.  This option is mainly included
     for use in testing.

These options are used by other ‘setuptools’ commands that modify
configuration files, such as the *note alias: 40. and *note setopt: 67.
commands.


File: setuptools.info,  Node: setopt - Set a distutils or setuptools option in a config file,  Next: test - Build package and run a unittest suite,  Prev: saveopts - Save used options to a configuration file,  Up: Command Reference

1.1.14.11 ‘setopt’ - Set a distutils or setuptools option in a config file
..........................................................................

This command is mainly for use by scripts, but it can also be used as a
quick and dirty way to change a distutils configuration option without
having to remember what file the options are in and then open an editor.

`Example 1'.  Set the default C compiler to ‘mingw32’ (using long option
names):

     setup.py setopt --command=build --option=compiler --set-value=mingw32

`Example 2'.  Remove any setting for the distutils default package
installation directory (short option names):

     setup.py setopt -c install -o install_lib -r

Options for the ‘setopt’ command:

‘--command=COMMAND, -c COMMAND’

     Command to set the option for.  This option is required.

‘--option=OPTION, -o OPTION’

     The name of the option to set.  This option is required.

‘--set-value=VALUE, -s VALUE’

     The value to set the option to.  Not needed if ‘-r’ or ‘--remove’
     is set.

‘--remove, -r’

     Remove (unset) the option, instead of setting it.

In addition to the above options, you may use any of the *note
configuration file options: 5d. (listed under the *note saveopts: 5e.
command, above) to determine which distutils configuration file the
option will be added to (or removed from).


File: setuptools.info,  Node: test - Build package and run a unittest suite,  Next: upload - Upload source and/or egg distributions to PyPI,  Prev: setopt - Set a distutils or setuptools option in a config file,  Up: Command Reference

1.1.14.12 ‘test’ - Build package and run a unittest suite
.........................................................

     Warning: ‘test’ is deprecated and will be removed in a future
     version.  Users looking for a generic test entry point independent
     of test runner are encouraged to use tox(1).

When doing test-driven development, or running automated builds that
need testing before they are deployed for downloading or use, it’s often
useful to be able to run a project’s unit tests without actually
deploying the project anywhere, even using the ‘develop’ command.  The
‘test’ command runs a project’s unit tests without actually deploying
it, by temporarily putting the project’s source on ‘sys.path’, after
first running ‘build_ext -i’ and ‘egg_info’ to ensure that any C
extensions and project metadata are up-to-date.

To use this command, your project’s tests must be wrapped in a
‘unittest’ test suite by either a function, a ‘TestCase’ class or
method, or a module or package containing ‘TestCase’ classes.  If the
named suite is a module, and the module has an ‘additional_tests()’
function, it is called and the result (which must be a
‘unittest.TestSuite’) is added to the tests to be run.  If the named
suite is a package, any submodules and subpackages are recursively added
to the overall test suite.  (Note: if your project specifies a
‘test_loader’, the rules for processing the chosen ‘test_suite’ may
differ; see the *note test_loader: 57. documentation for more details.)

Note that many test systems including ‘doctest’ support wrapping their
non-‘unittest’ tests in ‘TestSuite’ objects.  So, if you are using a
test package that does not support this, we suggest you encourage its
developers to implement test suite support, as this is a convenient and
standard way to aggregate a collection of tests to be run under a common
test harness.

By default, tests will be run in the “verbose” mode of the ‘unittest’
package’s text test runner, but you can get the “quiet” mode (just dots)
if you supply the ‘-q’ or ‘--quiet’ option, either as a global option to
the setup script (e.g.  ‘setup.py -q test’) or as an option for the
‘test’ command itself (e.g.  ‘setup.py test -q’).  There is one other
option available:

‘--test-suite=NAME, -s NAME’

     Specify the test suite (or module, class, or method) to be run
     (e.g.  ‘some_module.test_suite’).  The default for this option can
     be set by giving a ‘test_suite’ argument to the ‘setup()’ function,
     e.g.:

          setup(
              # ...
              test_suite="my_package.tests.test_all"
          )

     If you did not set a ‘test_suite’ in your ‘setup()’ call, and do
     not provide a ‘--test-suite’ option, an error will occur.

New in 41.5.0: Deprecated the test command.

   ---------- Footnotes ----------

   (1) https://tox.readthedocs.io


File: setuptools.info,  Node: upload - Upload source and/or egg distributions to PyPI,  Prev: test - Build package and run a unittest suite,  Up: Command Reference

1.1.14.13 ‘upload’ - Upload source and/or egg distributions to PyPI
...................................................................

The ‘upload’ command was deprecated in version 40.0 and removed in
version 42.0.  Use twine(1) instead.

For more information on the current best practices in uploading your
packages to PyPI, see the Python Packaging User Guide’s “Packaging
Python Projects” tutorial specifically the section on uploading the
distribution archives(2).

   ---------- Footnotes ----------

   (1) https://pypi.org/p/twine

   (2) 
https://packaging.python.org/tutorials/packaging-projects/#uploading-the-distribution-archives


File: setuptools.info,  Node: Using setuptools to package and distribute your project,  Next: Automatic Resource Extraction,  Prev: Command Reference,  Up: Transition to PEP517

1.1.15 Using setuptools to package and distribute your project
--------------------------------------------------------------

‘setuptools’ offers a variety of functionalities that make it easy to
build and distribute your python package.  Here we provide an overview
on the commonly used ones.


File: setuptools.info,  Node: Automatic Resource Extraction,  Next: Defining Additional Metadata,  Prev: Using setuptools to package and distribute your project,  Up: Transition to PEP517

1.1.16 Automatic Resource Extraction
------------------------------------

If you are using tools that expect your resources to be “real” files, or
your project includes non-extension native libraries or other files that
your C extensions expect to be able to access, you may need to list
those files in the ‘eager_resources’ argument to ‘setup()’, so that the
files will be extracted together, whenever a C extension in the project
is imported.

This is especially important if your project includes shared libraries
`other' than distutils-built C extensions, and those shared libraries
use file extensions other than ‘.dll’, ‘.so’, or ‘.dylib’, which are the
extensions that setuptools 0.6a8 and higher automatically detects as
shared libraries and adds to the ‘native_libs.txt’ file for you.  Any
shared libraries whose names do not end with one of those extensions
should be listed as ‘eager_resources’, because they need to be present
in the filesystem when he C extensions that link to them are used.

The ‘pkg_resources’ runtime for compressed packages will automatically
extract `all' C extensions and ‘eager_resources’ at the same time,
whenever `any' C extension or eager resource is requested via the
‘resource_filename()’ API. (C extensions are imported using
‘resource_filename()’ internally.)  This ensures that C extensions will
see all of the “real” files that they expect to see.

Note also that you can list directory resource names in
‘eager_resources’ as well, in which case the directory’s contents
(including subdirectories) will be extracted whenever any C extension or
eager resource is requested.

Please note that if you’re not sure whether you need to use this
argument, you don’t!  It’s really intended to support projects with lots
of non-Python dependencies and as a last resort for crufty projects that
can’t otherwise handle being compressed.  If your package is pure
Python, Python plus data files, or Python plus C, you really don’t need
this.  You’ve got to be using either C or an external program that needs
“real” files in your project before there’s any possibility of
‘eager_resources’ being relevant to your project.


File: setuptools.info,  Node: Defining Additional Metadata,  Next: Setting the zip_safe flag,  Prev: Automatic Resource Extraction,  Up: Transition to PEP517

1.1.17 Defining Additional Metadata
-----------------------------------

Some extensible applications and frameworks may need to define their own
kinds of metadata to include in eggs, which they can then access using
the ‘pkg_resources’ metadata APIs.  Ordinarily, this is done by having
plugin developers include additional files in their
‘ProjectName.egg-info’ directory.  However, since it can be tedious to
create such files by hand, you may want to create a distutils extension
that will create the necessary files from arguments to ‘setup()’, in
much the same way that ‘setuptools’ does for many of the ‘setup()’
arguments it adds.  See the section below on *note Creating distutils
Extensions: 46. for more details, especially the subsection on *note
Adding new EGG-INFO Files: 4b.


File: setuptools.info,  Node: Setting the zip_safe flag,  Prev: Defining Additional Metadata,  Up: Transition to PEP517

1.1.18 Setting the ‘zip_safe’ flag
----------------------------------

For some use cases (such as bundling as part of a larger application),
Python packages may be run directly from a zip file.  Not all packages,
however, are capable of running in compressed form, because they may
expect to be able to access either source code or data files as normal
operating system files.  So, ‘setuptools’ can install your project as a
zipfile or a directory, and its default choice is determined by the
project’s ‘zip_safe’ flag.

You can pass a True or False value for the ‘zip_safe’ argument to the
‘setup()’ function, or you can omit it.  If you omit it, the ‘bdist_egg’
command will analyze your project’s contents to see if it can detect any
conditions that would prevent it from working in a zipfile.  It will
output notices to the console about any such conditions that it finds.

Currently, this analysis is extremely conservative: it will consider the
project unsafe if it contains any C extensions or datafiles whatsoever.
This does `not' mean that the project can’t or won’t work as a zipfile!
It just means that the ‘bdist_egg’ authors aren’t yet comfortable
asserting that the project `will' work.  If the project contains no C or
data files, and does no ‘__file__’ or ‘__path__’ introspection or source
code manipulation, then there is an extremely solid chance the project
will work when installed as a zipfile.  (And if the project uses
‘pkg_resources’ for all its data file access, then C extensions and
other data files shouldn’t be a problem at all.  See the *note Accessing
Data Files at Runtime: 33. section above for more information.)

However, if ‘bdist_egg’ can’t be `sure' that your package will work, but
you’ve checked over all the warnings it issued, and you are either
satisfied it `will' work (or if you want to try it for yourself), then
you should set ‘zip_safe’ to ‘True’ in your ‘setup()’ call.  If it turns
out that it doesn’t work, you can always change it to ‘False’, which
will force ‘setuptools’ to install your project as a directory rather
than as a zipfile.

In the future, as we gain more experience with different packages and
become more satisfied with the robustness of the ‘pkg_resources’
runtime, the “zip safety” analysis may become less conservative.
However, we strongly recommend that you determine for yourself whether
your project functions correctly when installed as a zipfile, correct
any problems if you can, and then make an explicit declaration of ‘True’
or ‘False’ for the ‘zip_safe’ flag, so that it will not be necessary for
‘bdist_egg’ to try to guess whether your project can work as a zipfile.


File: setuptools.info,  Node: Build System Support,  Next: Package Discovery and Resource Access using pkg_resources,  Prev: Building and Distributing Packages with Setuptools,  Up: Top

2 Build System Support
**********************

* Menu:

* What is it?::
* How to use it?::


File: setuptools.info,  Node: What is it?,  Next: How to use it?,  Up: Build System Support

2.1 What is it?
===============

Python packaging has come a long way(1).

The traditional ‘setuptools’ way of packgaging Python modules uses a
‘setup()’ function within the ‘setup.py’ script.  Commands such as
‘python setup.py bdist’ or ‘python setup.py bdist_wheel’ generate a
distribution bundle and ‘python setup.py install’ installs the
distribution.  This interface makes it difficult to choose other
packaging tools without an overhaul.  Because ‘setup.py’ scripts allowed
for arbitrary execution, it proved difficult to provide a reliable user
experience across environments and history.

PEP 517(2) therefore came to rescue and specified a new standard to
package and distribute Python modules.  Under PEP 517:

     a ‘pyproject.toml’ file is used to specify what program to use for
     generating distribution.

     Then, two functions provided by the program,
     ‘build_wheel(directory: str)’ and ‘build_sdist(directory: str)’
     create the distribution bundle at the specified ‘directory’.  The
     program is free to use its own configuration script or extend the
     ‘.toml’ file.

     Lastly, ‘pip install *.whl’ or ‘pip install *.tar.gz’ does the
     actual installation.  If ‘*.whl’ is available, ‘pip’ will go ahead
     and copy the files into ‘site-packages’ directory.  If not, ‘pip’
     will look at ‘pyproject.toml’ and decide what program to use to
     ‘build from source’ (the default is ‘setuptools’)

With this standard, switching between packaging tools becomes a lot
easier.  ‘build_meta’ implements ‘setuptools’’ build system support.

   ---------- Footnotes ----------

   (1) https://www.bernat.tech/pep-517-518/

   (2) https://www.python.org/dev/peps/pep-0517/


File: setuptools.info,  Node: How to use it?,  Prev: What is it?,  Up: Build System Support

2.2 How to use it?
==================

Starting with a package that you want to distribute.  You will need your
source scripts, a ‘pyproject.toml’ file and a ‘setup.cfg’ file:

     ~/meowpkg/
         pyproject.toml
         setup.cfg
         meowpkg/__init__.py

The pyproject.toml file is required to specify the build system (i.e.
what is being used to package your scripts and install from source).  To
use it with setuptools, the content would be:

     [build-system]
     requires = ["setuptools", "wheel"]
     build-backend = "setuptools.build_meta"

Use ‘setuptools’’ *note declarative config: 50. to specify the package
information:

     [metadata]
     name = meowpkg
     version = 0.0.1
     description = a package that meows

     [options]
     packages = find:

Now generate the distribution.  Although the PyPA is still working to
provide a recommended tool(1) to build packages, the pep517 package(2)
provides this functionality.  To build the package:

     $ pip install -q pep517
     $ mkdir dist
     $ python -m pep517.build .

And now it’s done!  The ‘.whl’ file and ‘.tar.gz’ can then be
distributed and installed:

     dist/
         meowpkg-0.0.1.whl
         meowpkg-0.0.1.tar.gz

     $ pip install dist/meowpkg-0.0.1.whl

or:

     $ pip install dist/meowpkg-0.0.1.tar.gz

   ---------- Footnotes ----------

   (1) https://github.com/pypa/packaging-problems/issues/219

   (2) https://pypi.org/project/pep517


File: setuptools.info,  Node: Package Discovery and Resource Access using pkg_resources,  Next: Keywords,  Prev: Build System Support,  Up: Top

3 Package Discovery and Resource Access using ‘pkg_resources’
*************************************************************

The ‘pkg_resources’ module distributed with ‘setuptools’ provides an API
for Python libraries to access their resource files, and for extensible
applications and frameworks to automatically discover plugins.  It also
provides runtime support for using C extensions that are inside
zipfile-format eggs, support for merging packages that have
separately-distributed modules or subpackages, and APIs for managing
Python’s current “working set” of active packages.

* Menu:

* Overview::
* API Reference::


File: setuptools.info,  Node: Overview,  Next: API Reference,  Up: Package Discovery and Resource Access using pkg_resources

3.1 Overview
============

The ‘pkg_resources’ module provides runtime facilities for finding,
introspecting, activating and using installed Python distributions.
Some of the more advanced features (notably the support for parallel
installation of multiple versions) rely specifically on the “egg” format
(either as a zip archive or subdirectory), while others (such as plugin
discovery) will work correctly so long as “egg-info” metadata
directories are available for relevant distributions.

Eggs are a distribution format for Python modules, similar in concept to
Java’s “jars” or Ruby’s “gems”, or the “wheel” format defined in PEP
427.  However, unlike a pure distribution format, eggs can also be
installed and added directly to ‘sys.path’ as an import location.  When
installed in this way, eggs are `discoverable', meaning that they carry
metadata that unambiguously identifies their contents and dependencies.
This means that an installed egg can be `automatically' found and added
to ‘sys.path’ in response to simple requests of the form, “get me
everything I need to use docutils’ PDF support”.  This feature allows
mutually conflicting versions of a distribution to co-exist in the same
Python installation, with individual applications activating the desired
version at runtime by manipulating the contents of ‘sys.path’ (this
differs from the virtual environment approach, which involves creating
isolated environments for each application).

The following terms are needed in order to explain the capabilities
offered by this module:

project

     A library, framework, script, plugin, application, or collection of
     data or other resources, or some combination thereof.  Projects are
     assumed to have “relatively unique” names, e.g.  names registered
     with PyPI.

release

     A snapshot of a project at a particular point in time, denoted by a
     version identifier.

distribution

     A file or files that represent a particular release.

importable distribution

     A file or directory that, if placed on ‘sys.path’, allows Python to
     import any modules contained within it.

pluggable distribution

     An importable distribution whose filename unambiguously identifies
     its release (i.e.  project and version), and whose contents
     unambiguously specify what releases of other projects will satisfy
     its runtime requirements.

extra

     An “extra” is an optional feature of a release, that may impose
     additional runtime requirements.  For example, if docutils PDF
     support required a PDF support library to be present, docutils
     could define its PDF support as an “extra”, and list what other
     project releases need to be available in order to provide it.

environment

     A collection of distributions potentially available for importing,
     but not necessarily active.  More than one distribution (i.e.
     release version) for a given project may be present in an
     environment.

working set

     A collection of distributions actually available for importing, as
     on ‘sys.path’.  At most one distribution (release version) of a
     given project may be present in a working set, as otherwise there
     would be ambiguity as to what to import.

eggs

     Eggs are pluggable distributions in one of the three formats
     currently supported by ‘pkg_resources’.  There are built eggs,
     development eggs, and egg links.  Built eggs are directories or
     zipfiles whose name ends with ‘.egg’ and follows the egg naming
     conventions, and contain an ‘EGG-INFO’ subdirectory (zipped or
     otherwise).  Development eggs are normal directories of Python code
     with one or more ‘ProjectName.egg-info’ subdirectories.  The
     development egg format is also used to provide a default version of
     a distribution that is available to software that doesn’t use
     ‘pkg_resources’ to request specific versions.  Egg links are
     ‘*.egg-link’ files that contain the name of a built or development
     egg, to support symbolic linking on platforms that do not have
     native symbolic links (or where the symbolic link support is
     limited).

(For more information about these terms and concepts, see also this
architectural overview(1) of ‘pkg_resources’ and Python Eggs in
general.)

   ---------- Footnotes ----------

   (1) 
http://mail.python.org/pipermail/distutils-sig/2005-June/004652.html


File: setuptools.info,  Node: API Reference,  Prev: Overview,  Up: Package Discovery and Resource Access using pkg_resources

3.2 API Reference
=================

* Menu:

* Namespace Package Support::
* WorkingSet Objects::
* Environment Objects::
* Requirement Objects::
* Entry Points: Entry Points<2>.
* Distribution Objects::
* ResourceManager API::
* Metadata API::
* Exceptions::
* Supporting Custom Importers::
* Utility Functions::


File: setuptools.info,  Node: Namespace Package Support,  Next: WorkingSet Objects,  Up: API Reference

3.2.1 Namespace Package Support
-------------------------------

A namespace package is a package that only contains other packages and
modules, with no direct contents of its own.  Such packages can be split
across multiple, separately-packaged distributions.  They are normally
used to split up large packages produced by a single organization, such
as in the ‘zope’ namespace package for Zope Corporation packages, and
the ‘peak’ namespace package for the Python Enterprise Application Kit.

To create a namespace package, you list it in the ‘namespace_packages’
argument to ‘setup()’, in your project’s ‘setup.py’.  (See the *note
setuptools documentation on namespace packages: 1c. for more information
on this.)  Also, you must add a ‘declare_namespace()’ call in the
package’s ‘__init__.py’ file(s):

‘declare_namespace(name)’

     Declare that the dotted package name ‘name’ is a “namespace
     package” whose contained packages and modules may be spread across
     multiple distributions.  The named package’s ‘__path__’ will be
     extended to include the corresponding package in all distributions
     on ‘sys.path’ that contain a package of that name.  (More
     precisely, if an importer’s ‘find_module(name)’ returns a loader,
     then it will also be searched for the package’s contents.)
     Whenever a Distribution’s ‘activate()’ method is invoked, it checks
     for the presence of namespace packages and updates their ‘__path__’
     contents accordingly.

Applications that manipulate namespace packages or directly alter
‘sys.path’ at runtime may also need to use this API function:

‘fixup_namespace_packages(path_item)’

     Declare that ‘path_item’ is a newly added item on ‘sys.path’ that
     may need to be used to update existing namespace packages.
     Ordinarily, this is called for you when an egg is automatically
     added to ‘sys.path’, but if your application modifies ‘sys.path’ to
     include locations that may contain portions of a namespace package,
     you will need to call this function to ensure they are added to the
     existing namespace packages.

Although by default ‘pkg_resources’ only supports namespace packages for
filesystem and zip importers, you can extend its support to other
“importers” compatible with PEP 302 using the
‘register_namespace_handler()’ function.  See the section below on *note
Supporting Custom Importers: 7a. for details.


File: setuptools.info,  Node: WorkingSet Objects,  Next: Environment Objects,  Prev: Namespace Package Support,  Up: API Reference

3.2.2 ‘WorkingSet’ Objects
--------------------------

The ‘WorkingSet’ class provides access to a collection of “active”
distributions.  In general, there is only one meaningful ‘WorkingSet’
instance: the one that represents the distributions that are currently
active on ‘sys.path’.  This global instance is available under the name
‘working_set’ in the ‘pkg_resources’ module.  However, specialized tools
may wish to manipulate working sets that don’t correspond to ‘sys.path’,
and therefore may wish to create other ‘WorkingSet’ instances.

It’s important to note that the global ‘working_set’ object is
initialized from ‘sys.path’ when ‘pkg_resources’ is first imported, but
is only updated if you do all future ‘sys.path’ manipulation via
‘pkg_resources’ APIs.  If you manually modify ‘sys.path’, you must
invoke the appropriate methods on the ‘working_set’ instance to keep it
in sync.  Unfortunately, Python does not provide any way to detect
arbitrary changes to a list object like ‘sys.path’, so ‘pkg_resources’
cannot automatically update the ‘working_set’ based on changes to
‘sys.path’.

‘WorkingSet(entries=None)’

     Create a ‘WorkingSet’ from an iterable of path entries.  If
     ‘entries’ is not supplied, it defaults to the value of ‘sys.path’
     at the time the constructor is called.

     Note that you will not normally construct ‘WorkingSet’ instances
     yourself, but instead you will implicitly or explicitly use the
     global ‘working_set’ instance.  For the most part, the
     ‘pkg_resources’ API is designed so that the ‘working_set’ is used
     by default, such that you don’t have to explicitly refer to it most
     of the time.

All distributions available directly on ‘sys.path’ will be activated
automatically when ‘pkg_resources’ is imported.  This behaviour can
cause version conflicts for applications which require non-default
versions of those distributions.  To handle this situation,
‘pkg_resources’ checks for a ‘__requires__’ attribute in the ‘__main__’
module when initializing the default working set, and uses this to
ensure a suitable version of each affected distribution is activated.
For example:

     __requires__ = ["CherryPy < 3"] # Must be set before pkg_resources import
     import pkg_resources

* Menu:

* Basic WorkingSet Methods::
* WorkingSet Methods and Attributes::
* Receiving Change Notifications::
* Locating Plugins::


File: setuptools.info,  Node: Basic WorkingSet Methods,  Next: WorkingSet Methods and Attributes,  Up: WorkingSet Objects

3.2.2.1 Basic ‘WorkingSet’ Methods
..................................

The following methods of ‘WorkingSet’ objects are also available as
module- level functions in ‘pkg_resources’ that apply to the default
‘working_set’ instance.  Thus, you can use e.g.
‘pkg_resources.require()’ as an abbreviation for
‘pkg_resources.working_set.require()’:

‘require(*requirements)’

     Ensure that distributions matching ‘requirements’ are activated

     ‘requirements’ must be a string or a (possibly-nested) sequence
     thereof, specifying the distributions and versions required.  The
     return value is a sequence of the distributions that needed to be
     activated to fulfill the requirements; all relevant distributions
     are included, even if they were already activated in this working
     set.

     For the syntax of requirement specifiers, see the section below on
     *note Requirements Parsing: 7d.

     In general, it should not be necessary for you to call this method
     directly.  It’s intended more for use in quick-and-dirty scripting
     and interactive interpreter hacking than for production use.  If
     you’re creating an actual library or application, it’s strongly
     recommended that you create a “setup.py” script using ‘setuptools’,
     and declare all your requirements there.  That way, tools like pip
     can automatically detect what requirements your package has, and
     deal with them accordingly.

     Note that calling ‘require('SomePackage')’ will not install
     ‘SomePackage’ if it isn’t already present.  If you need to do this,
     you should use the ‘resolve()’ method instead, which allows you to
     pass an ‘installer’ callback that will be invoked when a needed
     distribution can’t be found on the local machine.  You can then
     have this callback display a dialog, automatically download the
     needed distribution, or whatever else is appropriate for your
     application.  See the documentation below on the ‘resolve()’ method
     for more information, and also on the ‘obtain()’ method of
     ‘Environment’ objects.

‘run_script(requires, script_name)’

     Locate distribution specified by ‘requires’ and run its
     ‘script_name’ script.  ‘requires’ must be a string containing a
     requirement specifier.  (See *note Requirements Parsing: 7d. below
     for the syntax.)

     The script, if found, will be executed in `the caller’s globals'.
     That’s because this method is intended to be called from wrapper
     scripts that act as a proxy for the “real” scripts in a
     distribution.  A wrapper script usually doesn’t need to do anything
     but invoke this function with the correct arguments.

     If you need more control over the script execution environment, you
     probably want to use the ‘run_script()’ method of a ‘Distribution’
     object’s *note Metadata API: 7e. instead.

‘iter_entry_points(group, name=None)’

     Yield entry point objects from ‘group’ matching ‘name’

     If ‘name’ is None, yields all entry points in ‘group’ from all
     distributions in the working set, otherwise only ones matching both
     ‘group’ and ‘name’ are yielded.  Entry points are yielded from the
     active distributions in the order that the distributions appear in
     the working set.  (For the global ‘working_set’, this should be the
     same as the order that they are listed in ‘sys.path’.)  Note that
     within the entry points advertised by an individual distribution,
     there is no particular ordering.

     Please see the section below on *note Entry Points: 7f. for more
     information.


File: setuptools.info,  Node: WorkingSet Methods and Attributes,  Next: Receiving Change Notifications,  Prev: Basic WorkingSet Methods,  Up: WorkingSet Objects

3.2.2.2 ‘WorkingSet’ Methods and Attributes
...........................................

These methods are used to query or manipulate the contents of a specific
working set, so they must be explicitly invoked on a particular
‘WorkingSet’ instance:

‘add_entry(entry)’

     Add a path item to the ‘entries’, finding any distributions on it.
     You should use this when you add additional items to ‘sys.path’ and
     you want the global ‘working_set’ to reflect the change.  This
     method is also called by the ‘WorkingSet()’ constructor during
     initialization.

     This method uses ‘find_distributions(entry,True)’ to find
     distributions corresponding to the path entry, and then ‘add()’
     them.  ‘entry’ is always appended to the ‘entries’ attribute, even
     if it is already present, however.  (This is because ‘sys.path’ can
     contain the same value more than once, and the ‘entries’ attribute
     should be able to reflect this.)

‘__contains__(dist)’

     True if ‘dist’ is active in this ‘WorkingSet’.  Note that only one
     distribution for a given project can be active in a given
     ‘WorkingSet’.

‘__iter__()’

     Yield distributions for non-duplicate projects in the working set.
     The yield order is the order in which the items’ path entries were
     added to the working set.

‘find(req)’

     Find a distribution matching ‘req’ (a ‘Requirement’ instance).  If
     there is an active distribution for the requested project, this
     returns it, as long as it meets the version requirement specified
     by ‘req’.  But, if there is an active distribution for the project
     and it does `not' meet the ‘req’ requirement, ‘VersionConflict’ is
     raised.  If there is no active distribution for the requested
     project, ‘None’ is returned.

‘resolve(requirements, env=None, installer=None)’

     List all distributions needed to (recursively) meet ‘requirements’

     ‘requirements’ must be a sequence of ‘Requirement’ objects.  ‘env’,
     if supplied, should be an ‘Environment’ instance.  If not supplied,
     an ‘Environment’ is created from the working set’s ‘entries’.
     ‘installer’, if supplied, will be invoked with each requirement
     that cannot be met by an already-installed distribution; it should
     return a ‘Distribution’ or ‘None’.  (See the ‘obtain()’ method of
     *note Environment Objects: 81, below, for more information on the
     ‘installer’ argument.)

‘add(dist, entry=None)’

     Add ‘dist’ to working set, associated with ‘entry’

     If ‘entry’ is unspecified, it defaults to ‘dist.location’.  On exit
     from this routine, ‘entry’ is added to the end of the working set’s
     ‘.entries’ (if it wasn’t already present).

     ‘dist’ is only added to the working set if it’s for a project that
     doesn’t already have a distribution active in the set.  If it’s
     successfully added, any callbacks registered with the ‘subscribe()’
     method will be called.  (See *note Receiving Change Notifications:
     82, below.)

     Note: ‘add()’ is automatically called for you by the ‘require()’
     method, so you don’t normally need to use this method directly.

‘entries’

     This attribute represents a “shadow” ‘sys.path’, primarily useful
     for debugging.  If you are experiencing import problems, you should
     check the global ‘working_set’ object’s ‘entries’ against
     ‘sys.path’, to ensure that they match.  If they do not, then some
     part of your program is manipulating ‘sys.path’ without updating
     the ‘working_set’ accordingly.  IMPORTANT NOTE: do not directly
     manipulate this attribute!  Setting it equal to ‘sys.path’ will not
     fix your problem, any more than putting black tape over an “engine
     warning” light will fix your car!  If this attribute is out of sync
     with ‘sys.path’, it’s merely an `indicator' of the problem, not the
     cause of it.


File: setuptools.info,  Node: Receiving Change Notifications,  Next: Locating Plugins,  Prev: WorkingSet Methods and Attributes,  Up: WorkingSet Objects

3.2.2.3 Receiving Change Notifications
......................................

Extensible applications and frameworks may need to receive notification
when a new distribution (such as a plug-in component) has been added to
a working set.  This is what the ‘subscribe()’ method and
‘add_activation_listener()’ function are for.

‘subscribe(callback)’

     Invoke ‘callback(distribution)’ once for each active distribution
     that is in the set now, or gets added later.  Because the callback
     is invoked for already-active distributions, you do not need to
     loop over the working set yourself to deal with the existing items;
     just register the callback and be prepared for the fact that it
     will be called immediately by this method.

     Note that callbacks `must not' allow exceptions to propagate, or
     they will interfere with the operation of other callbacks and
     possibly result in an inconsistent working set state.  Callbacks
     should use a try/except block to ignore, log, or otherwise process
     any errors, especially since the code that caused the callback to
     be invoked is unlikely to be able to handle the errors any better
     than the callback itself.

‘pkg_resources.add_activation_listener()’ is an alternate spelling of
‘pkg_resources.working_set.subscribe()’.


File: setuptools.info,  Node: Locating Plugins,  Prev: Receiving Change Notifications,  Up: WorkingSet Objects

3.2.2.4 Locating Plugins
........................

Extensible applications will sometimes have a “plugin directory” or a
set of plugin directories, from which they want to load entry points or
other metadata.  The ‘find_plugins()’ method allows you to do this, by
scanning an environment for the newest version of each project that can
be safely loaded without conflicts or missing requirements.

‘find_plugins(plugin_env, full_env=None, fallback=True)’

     Scan ‘plugin_env’ and identify which distributions could be added
     to this working set without version conflicts or missing
     requirements.

     Example usage:

          distributions, errors = working_set.find_plugins(
              Environment(plugin_dirlist)
          )
          map(working_set.add, distributions)  # add plugins+libs to sys.path
          print "Couldn't load", errors        # display errors

     The ‘plugin_env’ should be an ‘Environment’ instance that contains
     only distributions that are in the project’s “plugin directory” or
     directories.  The ‘full_env’, if supplied, should be an
     ‘Environment’ instance that contains all currently-available
     distributions.

     If ‘full_env’ is not supplied, one is created automatically from
     the ‘WorkingSet’ this method is called on, which will typically
     mean that every directory on ‘sys.path’ will be scanned for
     distributions.

     This method returns a 2-tuple: (‘distributions’, ‘error_info’),
     where ‘distributions’ is a list of the distributions found in
     ‘plugin_env’ that were loadable, along with any other distributions
     that are needed to resolve their dependencies.  ‘error_info’ is a
     dictionary mapping unloadable plugin distributions to an exception
     instance describing the error that occurred.  Usually this will be
     a ‘DistributionNotFound’ or ‘VersionConflict’ instance.

     Most applications will use this method mainly on the master
     ‘working_set’ instance in ‘pkg_resources’, and then immediately add
     the returned distributions to the working set so that they are
     available on sys.path.  This will make it possible to find any
     entry points, and allow any other metadata tracking and hooks to be
     activated.

     The resolution algorithm used by ‘find_plugins()’ is as follows.
     First, the project names of the distributions present in
     ‘plugin_env’ are sorted.  Then, each project’s eggs are tried in
     descending version order (i.e., newest version first).

     An attempt is made to resolve each egg’s dependencies.  If the
     attempt is successful, the egg and its dependencies are added to
     the output list and to a temporary copy of the working set.  The
     resolution process continues with the next project name, and no
     older eggs for that project are tried.

     If the resolution attempt fails, however, the error is added to the
     error dictionary.  If the ‘fallback’ flag is true, the next older
     version of the plugin is tried, until a working version is found.
     If false, the resolution process continues with the next plugin
     project name.

     Some applications may have stricter fallback requirements than
     others.  For example, an application that has a database schema or
     persistent objects may not be able to safely downgrade a version of
     a package.  Others may want to ensure that a new plugin
     configuration is either 100% good or else revert to a known-good
     configuration.  (That is, they may wish to revert to a known
     configuration if the ‘error_info’ return value is non-empty.)

     Note that this algorithm gives precedence to satisfying the
     dependencies of alphabetically prior project names in case of
     version conflicts.  If two projects named “AaronsPlugin” and
     “ZekesPlugin” both need different versions of “TomsLibrary”, then
     “AaronsPlugin” will win and “ZekesPlugin” will be disabled due to
     version conflict.


File: setuptools.info,  Node: Environment Objects,  Next: Requirement Objects,  Prev: WorkingSet Objects,  Up: API Reference

3.2.3 ‘Environment’ Objects
---------------------------

An “environment” is a collection of ‘Distribution’ objects, usually ones
that are present and potentially importable on the current platform.
‘Environment’ objects are used by ‘pkg_resources’ to index available
distributions during dependency resolution.

‘Environment(search_path=None, platform=get_supported_platform(), python=PY_MAJOR)’

     Create an environment snapshot by scanning ‘search_path’ for
     distributions compatible with ‘platform’ and ‘python’.
     ‘search_path’ should be a sequence of strings such as might be used
     on ‘sys.path’.  If a ‘search_path’ isn’t supplied, ‘sys.path’ is
     used.

     ‘platform’ is an optional string specifying the name of the
     platform that platform-specific distributions must be compatible
     with.  If unspecified, it defaults to the current platform.
     ‘python’ is an optional string naming the desired version of Python
     (e.g.  ‘'2.4'’); it defaults to the currently-running version.

     You may explicitly set ‘platform’ (and/or ‘python’) to ‘None’ if
     you wish to include `all' distributions, not just those compatible
     with the running platform or Python version.

     Note that ‘search_path’ is scanned immediately for distributions,
     and the resulting ‘Environment’ is a snapshot of the found
     distributions.  It is not automatically updated if the system’s
     state changes due to e.g.  installation or removal of
     distributions.

‘__getitem__(project_name)’

     Returns a list of distributions for the given project name, ordered
     from newest to oldest version.  (And highest to lowest format
     precedence for distributions that contain the same version of the
     project.)  If there are no distributions for the project, returns
     an empty list.

‘__iter__()’

     Yield the unique project names of the distributions in this
     environment.  The yielded names are always in lower case.

‘add(dist)’

     Add ‘dist’ to the environment if it matches the platform and python
     version specified at creation time, and only if the distribution
     hasn’t already been added.  (i.e., adding the same distribution
     more than once is a no-op.)

‘remove(dist)’

     Remove ‘dist’ from the environment.

‘can_add(dist)’

     Is distribution ‘dist’ acceptable for this environment?  If it’s
     not compatible with the ‘platform’ and ‘python’ version values
     specified when the environment was created, a false value is
     returned.

‘__add__(dist_or_env)’ (‘+’ operator)

     Add a distribution or environment to an ‘Environment’ instance,
     returning a `new' environment object that contains all the
     distributions previously contained by both.  The new environment
     will have a ‘platform’ and ‘python’ of ‘None’, meaning that it will
     not reject any distributions from being added to it; it will simply
     accept whatever is added.  If you want the added items to be
     filtered for platform and Python version, or you want to add them
     to the `same' environment instance, you should use in-place
     addition (‘+=’) instead.

‘__iadd__(dist_or_env)’ (‘+=’ operator)

     Add a distribution or environment to an ‘Environment’ instance
     `in-place', updating the existing instance and returning it.  The
     ‘platform’ and ‘python’ filter attributes take effect, so
     distributions in the source that do not have a suitable platform
     string or Python version are silently ignored.

‘best_match(req, working_set, installer=None)’

     Find distribution best matching ‘req’ and usable on ‘working_set’

     This calls the ‘find(req)’ method of the ‘working_set’ to see if a
     suitable distribution is already active.  (This may raise
     ‘VersionConflict’ if an unsuitable version of the project is
     already active in the specified ‘working_set’.)  If a suitable
     distribution isn’t active, this method returns the newest
     distribution in the environment that meets the ‘Requirement’ in
     ‘req’.  If no suitable distribution is found, and ‘installer’ is
     supplied, then the result of calling the environment’s ‘obtain(req,
     installer)’ method will be returned.

‘obtain(requirement, installer=None)’

     Obtain a distro that matches requirement (e.g.  via download).  In
     the base ‘Environment’ class, this routine just returns
     ‘installer(requirement)’, unless ‘installer’ is None, in which case
     None is returned instead.  This method is a hook that allows
     subclasses to attempt other ways of obtaining a distribution before
     falling back to the ‘installer’ argument.

‘scan(search_path=None)’

     Scan ‘search_path’ for distributions usable on ‘platform’

     Any distributions found are added to the environment.
     ‘search_path’ should be a sequence of strings such as might be used
     on ‘sys.path’.  If not supplied, ‘sys.path’ is used.  Only
     distributions conforming to the platform/python version defined at
     initialization are added.  This method is a shortcut for using the
     ‘find_distributions()’ function to find the distributions from each
     item in ‘search_path’, and then calling ‘add()’ to add each one to
     the environment.


File: setuptools.info,  Node: Requirement Objects,  Next: Entry Points<2>,  Prev: Environment Objects,  Up: API Reference

3.2.4 ‘Requirement’ Objects
---------------------------

‘Requirement’ objects express what versions of a project are suitable
for some purpose.  These objects (or their string form) are used by
various ‘pkg_resources’ APIs in order to find distributions that a
script or distribution needs.

* Menu:

* Requirements Parsing::
* Requirement Methods and Attributes::


File: setuptools.info,  Node: Requirements Parsing,  Next: Requirement Methods and Attributes,  Up: Requirement Objects

3.2.4.1 Requirements Parsing
............................

‘parse_requirements(s)’

     Yield ‘Requirement’ objects for a string or iterable of lines.
     Each requirement must start on a new line.  See below for syntax.

‘Requirement.parse(s)’

     Create a ‘Requirement’ object from a string or iterable of lines.
     A ‘ValueError’ is raised if the string or lines do not contain a
     valid requirement specifier, or if they contain more than one
     specifier.  (To parse multiple specifiers from a string or iterable
     of strings, use ‘parse_requirements()’ instead.)

     The syntax of a requirement specifier is defined in full in PEP
     508.

     Some examples of valid requirement specifiers:

          FooProject >= 1.2
          Fizzy [foo, bar]
          PickyThing>1.6,<=1.9,!=1.8.6
          SomethingWhoseVersionIDontCareAbout
          SomethingWithMarker[foo]>1.0;python_version<"2.7"

     The project name is the only required portion of a requirement
     string, and if it’s the only thing supplied, the requirement will
     accept any version of that project.

     The “extras” in a requirement are used to request optional features
     of a project, that may require additional project distributions in
     order to function.  For example, if the hypothetical
     “Report-O-Rama” project offered optional PDF support, it might
     require an additional library in order to provide that support.
     Thus, a project needing Report-O-Rama’s PDF features could use a
     requirement of ‘Report-O-Rama[PDF]’ to request installation or
     activation of both Report-O-Rama and any libraries it needs in
     order to provide PDF support.  For example, you could use:

          pip install Report-O-Rama[PDF]

     To install the necessary packages using pip, or call
     ‘pkg_resources.require('Report-O-Rama[PDF]')’ to add the necessary
     distributions to sys.path at runtime.

     The “markers” in a requirement are used to specify when a
     requirement should be installed – the requirement will be installed
     if the marker evaluates as true in the current environment.  For
     example, specifying ‘argparse;python_version<"3.0"’ will not
     install in an Python 3 environment, but will in a Python 2
     environment.


File: setuptools.info,  Node: Requirement Methods and Attributes,  Prev: Requirements Parsing,  Up: Requirement Objects

3.2.4.2 ‘Requirement’ Methods and Attributes
............................................

‘__contains__(dist_or_version)’

     Return true if ‘dist_or_version’ fits the criteria for this
     requirement.  If ‘dist_or_version’ is a ‘Distribution’ object, its
     project name must match the requirement’s project name, and its
     version must meet the requirement’s version criteria.  If
     ‘dist_or_version’ is a string, it is parsed using the
     ‘parse_version()’ utility function.  Otherwise, it is assumed to be
     an already-parsed version.

     The ‘Requirement’ object’s version specifiers (‘.specs’) are
     internally sorted into ascending version order, and used to
     establish what ranges of versions are acceptable.  Adjacent
     redundant conditions are effectively consolidated (e.g.  ‘">1, >2"’
     produces the same results as ‘">2"’, and ‘"<2,<3"’ produces the
     same results as ‘"<2"’).  ‘"!="’ versions are excised from the
     ranges they fall within.  The version being tested for
     acceptability is then checked for membership in the resulting
     ranges.

‘__eq__(other_requirement)’

     A requirement compares equal to another requirement if they have
     case-insensitively equal project names, version specifiers, and
     “extras”.  (The order that extras and version specifiers are in is
     also ignored.)  Equal requirements also have equal hashes, so that
     requirements can be used in sets or as dictionary keys.

‘__str__()’

     The string form of a ‘Requirement’ is a string that, if passed to
     ‘Requirement.parse()’, would return an equal ‘Requirement’ object.

‘project_name’

     The name of the required project

‘key’

     An all-lowercase version of the ‘project_name’, useful for
     comparison or indexing.

‘extras’

     A tuple of names of “extras” that this requirement calls for.
     (These will be all-lowercase and normalized using the
     ‘safe_extra()’ parsing utility function, so they may not exactly
     equal the extras the requirement was created with.)

‘specs’

     A list of ‘(op,version)’ tuples, sorted in ascending parsed-version
     order.  The ‘op’ in each tuple is a comparison operator,
     represented as a string.  The ‘version’ is the (unparsed) version
     number.

‘marker’

     An instance of ‘packaging.markers.Marker’ that allows evaluation
     against the current environment.  May be None if no marker
     specified.

‘url’

     The location to download the requirement from if specified.


File: setuptools.info,  Node: Entry Points<2>,  Next: Distribution Objects,  Prev: Requirement Objects,  Up: API Reference

3.2.5 Entry Points
------------------

Entry points are a simple way for distributions to “advertise” Python
objects (such as functions or classes) for use by other distributions.
Extensible applications and frameworks can search for entry points with
a particular name or group, either from a specific distribution or from
all active distributions on sys.path, and then inspect or load the
advertised objects at will.

Entry points belong to “groups” which are named with a dotted name
similar to a Python package or module name.  For example, the
‘setuptools’ package uses an entry point named ‘distutils.commands’ in
order to find commands defined by distutils extensions.  ‘setuptools’
treats the names of entry points defined in that group as the acceptable
commands for a setup script.

In a similar way, other packages can define their own entry point
groups, either using dynamic names within the group (like
‘distutils.commands’), or possibly using predefined names within the
group.  For example, a blogging framework that offers various pre- or
post-publishing hooks might define an entry point group and look for
entry points named “pre_process” and “post_process” within that group.

To advertise an entry point, a project needs to use ‘setuptools’ and
provide an ‘entry_points’ argument to ‘setup()’ in its setup script, so
that the entry points will be included in the distribution’s metadata.
For more details, see the [‘setuptools’
documentation](‘https://setuptools.readthedocs.io/en/latest/setuptools.html#dynamic-discovery-of-services-and-plugins’).

Each project distribution can advertise at most one entry point of a
given name within the same entry point group.  For example, a distutils
extension could advertise two different ‘distutils.commands’ entry
points, as long as they had different names.  However, there is nothing
that prevents `different' projects from advertising entry points of the
same name in the same group.  In some cases, this is a desirable thing,
since the application or framework that uses the entry points may be
calling them as hooks, or in some other way combining them.  It is up to
the application or framework to decide what to do if multiple
distributions advertise an entry point; some possibilities include using
both entry points, displaying an error message, using the first one
found in sys.path order, etc.

* Menu:

* Convenience API::
* Creating and Parsing::
* EntryPoint Objects::


File: setuptools.info,  Node: Convenience API,  Next: Creating and Parsing,  Up: Entry Points<2>

3.2.5.1 Convenience API
.......................

In the following functions, the ‘dist’ argument can be a ‘Distribution’
instance, a ‘Requirement’ instance, or a string specifying a requirement
(i.e.  project name, version, etc.).  If the argument is a string or
‘Requirement’, the specified distribution is located (and added to
sys.path if not already present).  An error will be raised if a matching
distribution is not available.

The ‘group’ argument should be a string containing a dotted identifier,
identifying an entry point group.  If you are defining an entry point
group, you should include some portion of your package’s name in the
group name so as to avoid collision with other packages’ entry point
groups.

‘load_entry_point(dist, group, name)’

     Load the named entry point from the specified distribution, or
     raise ‘ImportError’.

‘get_entry_info(dist, group, name)’

     Return an ‘EntryPoint’ object for the given ‘group’ and ‘name’ from
     the specified distribution.  Returns ‘None’ if the distribution has
     not advertised a matching entry point.

‘get_entry_map(dist, group=None)’

     Return the distribution’s entry point map for ‘group’, or the full
     entry map for the distribution.  This function always returns a
     dictionary, even if the distribution advertises no entry points.
     If ‘group’ is given, the dictionary maps entry point names to the
     corresponding ‘EntryPoint’ object.  If ‘group’ is None, the
     dictionary maps group names to dictionaries that then map entry
     point names to the corresponding ‘EntryPoint’ instance in that
     group.

‘iter_entry_points(group, name=None)’

     Yield entry point objects from ‘group’ matching ‘name’.

     If ‘name’ is None, yields all entry points in ‘group’ from all
     distributions in the working set on sys.path, otherwise only ones
     matching both ‘group’ and ‘name’ are yielded.  Entry points are
     yielded from the active distributions in the order that the
     distributions appear on sys.path.  (Within entry points for a
     particular distribution, however, there is no particular ordering.)

     (This API is actually a method of the global ‘working_set’ object;
     see the section above on *note Basic WorkingSet Methods: 7c. for
     more information.)


File: setuptools.info,  Node: Creating and Parsing,  Next: EntryPoint Objects,  Prev: Convenience API,  Up: Entry Points<2>

3.2.5.2 Creating and Parsing
............................

‘EntryPoint(name, module_name, attrs=(), extras=(), dist=None)’

     Create an ‘EntryPoint’ instance.  ‘name’ is the entry point name.
     The ‘module_name’ is the (dotted) name of the module containing the
     advertised object.  ‘attrs’ is an optional tuple of names to look
     up from the module to obtain the advertised object.  For example,
     an ‘attrs’ of ‘("foo","bar")’ and a ‘module_name’ of ‘"baz"’ would
     mean that the advertised object could be obtained by the following
     code:

          import baz
          advertised_object = baz.foo.bar

     The ‘extras’ are an optional tuple of “extra feature” names that
     the distribution needs in order to provide this entry point.  When
     the entry point is loaded, these extra features are looked up in
     the ‘dist’ argument to find out what other distributions may need
     to be activated on sys.path; see the ‘load()’ method for more
     details.  The ‘extras’ argument is only meaningful if ‘dist’ is
     specified.  ‘dist’ must be a ‘Distribution’ instance.

‘EntryPoint.parse(src, dist=None)’ (classmethod)

     Parse a single entry point from string ‘src’

     Entry point syntax follows the form:

          name = some.module:some.attr [extra1,extra2]

     The entry name and module name are required, but the ‘:attrs’ and
     ‘[extras]’ parts are optional, as is the whitespace shown between
     some of the items.  The ‘dist’ argument is passed through to the
     ‘EntryPoint()’ constructor, along with the other values parsed from
     ‘src’.

‘EntryPoint.parse_group(group, lines, dist=None)’ (classmethod)

     Parse ‘lines’ (a string or sequence of lines) to create a
     dictionary mapping entry point names to ‘EntryPoint’ objects.
     ‘ValueError’ is raised if entry point names are duplicated, if
     ‘group’ is not a valid entry point group name, or if there are any
     syntax errors.  (Note: the ‘group’ parameter is used only for
     validation and to create more informative error messages.)  If
     ‘dist’ is provided, it will be used to set the ‘dist’ attribute of
     the created ‘EntryPoint’ objects.

‘EntryPoint.parse_map(data, dist=None)’ (classmethod)

     Parse ‘data’ into a dictionary mapping group names to dictionaries
     mapping entry point names to ‘EntryPoint’ objects.  If ‘data’ is a
     dictionary, then the keys are used as group names and the values
     are passed to ‘parse_group()’ as the ‘lines’ argument.  If ‘data’
     is a string or sequence of lines, it is first split into .ini-style
     sections (using the ‘split_sections()’ utility function) and the
     section names are used as group names.  In either case, the ‘dist’
     argument is passed through to ‘parse_group()’ so that the entry
     points will be linked to the specified distribution.


File: setuptools.info,  Node: EntryPoint Objects,  Prev: Creating and Parsing,  Up: Entry Points<2>

3.2.5.3 ‘EntryPoint’ Objects
............................

For simple introspection, ‘EntryPoint’ objects have attributes that
correspond exactly to the constructor argument names: ‘name’,
‘module_name’, ‘attrs’, ‘extras’, and ‘dist’ are all available.  In
addition, the following methods are provided:

‘load()’

     Load the entry point, returning the advertised Python object.
     Effectively calls ‘self.require()’ then returns ‘self.resolve()’.

‘require(env=None, installer=None)’

     Ensure that any “extras” needed by the entry point are available on
     sys.path.  ‘UnknownExtra’ is raised if the ‘EntryPoint’ has
     ‘extras’, but no ‘dist’, or if the named extras are not defined by
     the distribution.  If ‘env’ is supplied, it must be an
     ‘Environment’, and it will be used to search for needed
     distributions if they are not already present on sys.path.  If
     ‘installer’ is supplied, it must be a callable taking a
     ‘Requirement’ instance and returning a matching importable
     ‘Distribution’ instance or None.

‘resolve()’

     Resolve the entry point from its module and attrs, returning the
     advertised Python object.  Raises ‘ImportError’ if it cannot be
     obtained.

‘__str__()’

     The string form of an ‘EntryPoint’ is a string that could be passed
     to ‘EntryPoint.parse()’ to produce an equivalent ‘EntryPoint’.


File: setuptools.info,  Node: Distribution Objects,  Next: ResourceManager API,  Prev: Entry Points<2>,  Up: API Reference

3.2.6 ‘Distribution’ Objects
----------------------------

‘Distribution’ objects represent collections of Python code that may or
may not be importable, and may or may not have metadata and resources
associated with them.  Their metadata may include information such as
what other projects the distribution depends on, what entry points the
distribution advertises, and so on.

* Menu:

* Getting or Creating Distributions::
* Distribution Attributes::
* Distribution Methods::


File: setuptools.info,  Node: Getting or Creating Distributions,  Next: Distribution Attributes,  Up: Distribution Objects

3.2.6.1 Getting or Creating Distributions
.........................................

Most commonly, you’ll obtain ‘Distribution’ objects from a ‘WorkingSet’
or an ‘Environment’.  (See the sections above on *note WorkingSet
Objects: 7b. and *note Environment Objects: 81, which are containers for
active distributions and available distributions, respectively.)  You
can also obtain ‘Distribution’ objects from one of these high-level
APIs:

‘find_distributions(path_item, only=False)’

     Yield distributions accessible via ‘path_item’.  If ‘only’ is true,
     yield only distributions whose ‘location’ is equal to ‘path_item’.
     In other words, if ‘only’ is true, this yields any distributions
     that would be importable if ‘path_item’ were on ‘sys.path’.  If
     ‘only’ is false, this also yields distributions that are “in” or
     “under” ‘path_item’, but would not be importable unless their
     locations were also added to ‘sys.path’.

‘get_distribution(dist_spec)’

     Return a ‘Distribution’ object for a given ‘Requirement’ or string.
     If ‘dist_spec’ is already a ‘Distribution’ instance, it is
     returned.  If it is a ‘Requirement’ object or a string that can be
     parsed into one, it is used to locate and activate a matching
     distribution, which is then returned.

However, if you’re creating specialized tools for working with
distributions, or creating a new distribution format, you may also need
to create ‘Distribution’ objects directly, using one of the three
constructors below.

These constructors all take an optional ‘metadata’ argument, which is
used to access any resources or metadata associated with the
distribution.  ‘metadata’ must be an object that implements the
‘IResourceProvider’ interface, or None.  If it is None, an
‘EmptyProvider’ is used instead.  ‘Distribution’ objects implement both
the *note IResourceProvider: 8b. and *note IMetadataProvider Methods:
8c. by delegating them to the ‘metadata’ object.

‘Distribution.from_location(location, basename, metadata=None, **kw)’ (classmethod)

     Create a distribution for ‘location’, which must be a string such
     as a URL, filename, or other string that might be used on
     ‘sys.path’.  ‘basename’ is a string naming the distribution, like
     ‘Foo-1.2-py2.4.egg’.  If ‘basename’ ends with ‘.egg’, then the
     project’s name, version, python version and platform are extracted
     from the filename and used to set those properties of the created
     distribution.  Any additional keyword arguments are forwarded to
     the ‘Distribution()’ constructor.

‘Distribution.from_filename(filename, metadata=None**kw)’ (classmethod)

     Create a distribution by parsing a local filename.  This is a
     shorter way of saying
     ‘Distribution.from_location(normalize_path(filename),
     os.path.basename(filename), metadata)’.  In other words, it creates
     a distribution whose location is the normalize form of the
     filename, parsing name and version information from the base
     portion of the filename.  Any additional keyword arguments are
     forwarded to the ‘Distribution()’ constructor.

‘Distribution(location,metadata,project_name,version,py_version,platform,precedence)’

     Create a distribution by setting its properties.  All arguments are
     optional and default to None, except for ‘py_version’ (which
     defaults to the current Python version) and ‘precedence’ (which
     defaults to ‘EGG_DIST’; for more details see ‘precedence’ under
     *note Distribution Attributes: 8d. below).  Note that it’s usually
     easier to use the ‘from_filename()’ or ‘from_location()’
     constructors than to specify all these arguments individually.


File: setuptools.info,  Node: Distribution Attributes,  Next: Distribution Methods,  Prev: Getting or Creating Distributions,  Up: Distribution Objects

3.2.6.2 ‘Distribution’ Attributes
.................................

location

     A string indicating the distribution’s location.  For an importable
     distribution, this is the string that would be added to ‘sys.path’
     to make it actively importable.  For non-importable distributions,
     this is simply a filename, URL, or other way of locating the
     distribution.

project_name

     A string, naming the project that this distribution is for.
     Project names are defined by a project’s setup script, and they are
     used to identify projects on PyPI. When a ‘Distribution’ is
     constructed, the ‘project_name’ argument is passed through the
     ‘safe_name()’ utility function to filter out any unacceptable
     characters.

key

     ‘dist.key’ is short for ‘dist.project_name.lower()’.  It’s used for
     case-insensitive comparison and indexing of distributions by
     project name.

extras

     A list of strings, giving the names of extra features defined by
     the project’s dependency list (the ‘extras_require’ argument
     specified in the project’s setup script).

version

     A string denoting what release of the project this distribution
     contains.  When a ‘Distribution’ is constructed, the ‘version’
     argument is passed through the ‘safe_version()’ utility function to
     filter out any unacceptable characters.  If no ‘version’ is
     specified at construction time, then attempting to access this
     attribute later will cause the ‘Distribution’ to try to discover
     its version by reading its ‘PKG-INFO’ metadata file.  If ‘PKG-INFO’
     is unavailable or can’t be parsed, ‘ValueError’ is raised.

parsed_version

     The ‘parsed_version’ is an object representing a “parsed” form of
     the distribution’s ‘version’.  ‘dist.parsed_version’ is a shortcut
     for calling ‘parse_version(dist.version)’.  It is used to compare
     or sort distributions by version.  (See the *note Parsing
     Utilities: 8e. section below for more information on the
     ‘parse_version()’ function.)  Note that accessing ‘parsed_version’
     may result in a ‘ValueError’ if the ‘Distribution’ was constructed
     without a ‘version’ and without ‘metadata’ capable of supplying the
     missing version info.

py_version

     The major/minor Python version the distribution supports, as a
     string.  For example, “2.7” or “3.4”.  The default is the current
     version of Python.

platform

     A string representing the platform the distribution is intended
     for, or ‘None’ if the distribution is “pure Python” and therefore
     cross-platform.  See *note Platform Utilities: 8f. below for more
     information on platform strings.

precedence

     A distribution’s ‘precedence’ is used to determine the relative
     order of two distributions that have the same ‘project_name’ and
     ‘parsed_version’.  The default precedence is
     ‘pkg_resources.EGG_DIST’, which is the highest (i.e.  most
     preferred) precedence.  The full list of predefined precedences,
     from most preferred to least preferred, is: ‘EGG_DIST’,
     ‘BINARY_DIST’, ‘SOURCE_DIST’, ‘CHECKOUT_DIST’, and ‘DEVELOP_DIST’.
     Normally, precedences other than ‘EGG_DIST’ are used only by the
     ‘setuptools.package_index’ module, when sorting distributions found
     in a package index to determine their suitability for installation.
     “System” and “Development” eggs (i.e., ones that use the
     ‘.egg-info’ format), however, are automatically given a precedence
     of ‘DEVELOP_DIST’.


File: setuptools.info,  Node: Distribution Methods,  Prev: Distribution Attributes,  Up: Distribution Objects

3.2.6.3 ‘Distribution’ Methods
..............................

‘activate(path=None)’

     Ensure distribution is importable on ‘path’.  If ‘path’ is None,
     ‘sys.path’ is used instead.  This ensures that the distribution’s
     ‘location’ is in the ‘path’ list, and it also performs any
     necessary namespace package fixups or declarations.  (That is, if
     the distribution contains namespace packages, this method ensures
     that they are declared, and that the distribution’s contents for
     those namespace packages are merged with the contents provided by
     any other active distributions.  See the section above on *note
     Namespace Package Support: 79. for more information.)

     ‘pkg_resources’ adds a notification callback to the global
     ‘working_set’ that ensures this method is called whenever a
     distribution is added to it.  Therefore, you should not normally
     need to explicitly call this method.  (Note that this means that
     namespace packages on ‘sys.path’ are always imported as soon as
     ‘pkg_resources’ is, which is another reason why namespace packages
     should not contain any code or import statements.)

‘as_requirement()’

     Return a ‘Requirement’ instance that matches this distribution’s
     project name and version.

‘requires(extras=())’

     List the ‘Requirement’ objects that specify this distribution’s
     dependencies.  If ‘extras’ is specified, it should be a sequence of
     names of “extras” defined by the distribution, and the list
     returned will then include any dependencies needed to support the
     named “extras”.

‘clone(**kw)’

     Create a copy of the distribution.  Any supplied keyword arguments
     override the corresponding argument to the ‘Distribution()’
     constructor, allowing you to change some of the copied
     distribution’s attributes.

‘egg_name()’

     Return what this distribution’s standard filename should be, not
     including the “.egg” extension.  For example, a distribution for
     project “Foo” version 1.2 that runs on Python 2.3 for Windows would
     have an ‘egg_name()’ of ‘Foo-1.2-py2.3-win32’.  Any dashes in the
     name or version are converted to underscores.
     (‘Distribution.from_location()’ will convert them back when parsing
     a “.egg” file name.)

‘__cmp__(other)’, ‘__hash__()’

     Distribution objects are hashed and compared on the basis of their
     parsed version and precedence, followed by their key (lowercase
     project name), location, Python version, and platform.

The following methods are used to access ‘EntryPoint’ objects advertised
by the distribution.  See the section above on *note Entry Points: 7f.
for more detailed information about these operations:

‘get_entry_info(group, name)’

     Return the ‘EntryPoint’ object for ‘group’ and ‘name’, or None if
     no such point is advertised by this distribution.

‘get_entry_map(group=None)’

     Return the entry point map for ‘group’.  If ‘group’ is None, return
     a dictionary mapping group names to entry point maps for all
     groups.  (An entry point map is a dictionary of entry point names
     to ‘EntryPoint’ objects.)

‘load_entry_point(group, name)’

     Short for ‘get_entry_info(group, name).load()’.  Returns the object
     advertised by the named entry point, or raises ‘ImportError’ if the
     entry point isn’t advertised by this distribution, or there is some
     other import problem.

In addition to the above methods, ‘Distribution’ objects also implement
all of the *note IResourceProvider: 8b. and *note IMetadataProvider
Methods: 8c. (which are documented in later sections):

   * ‘has_metadata(name)’

   * ‘metadata_isdir(name)’

   * ‘metadata_listdir(name)’

   * ‘get_metadata(name)’

   * ‘get_metadata_lines(name)’

   * ‘run_script(script_name, namespace)’

   * ‘get_resource_filename(manager, resource_name)’

   * ‘get_resource_stream(manager, resource_name)’

   * ‘get_resource_string(manager, resource_name)’

   * ‘has_resource(resource_name)’

   * ‘resource_isdir(resource_name)’

   * ‘resource_listdir(resource_name)’

If the distribution was created with a ‘metadata’ argument, these
resource and metadata access methods are all delegated to that
‘metadata’ provider.  Otherwise, they are delegated to an
‘EmptyProvider’, so that the distribution will appear to have no
resources or metadata.  This delegation approach is used so that
supporting custom importers or new distribution formats can be done
simply by creating an appropriate *note IResourceProvider: 8b.
implementation; see the section below on *note Supporting Custom
Importers: 7a. for more details.


File: setuptools.info,  Node: ResourceManager API,  Next: Metadata API,  Prev: Distribution Objects,  Up: API Reference

3.2.7 ‘ResourceManager’ API
---------------------------

The ‘ResourceManager’ class provides uniform access to package
resources, whether those resources exist as files and directories or are
compressed in an archive of some kind.

Normally, you do not need to create or explicitly manage
‘ResourceManager’ instances, as the ‘pkg_resources’ module creates a
global instance for you, and makes most of its methods available as
top-level names in the ‘pkg_resources’ module namespace.  So, for
example, this code actually calls the ‘resource_string()’ method of the
global ‘ResourceManager’:

     import pkg_resources
     my_data = pkg_resources.resource_string(__name__, "foo.dat")

Thus, you can use the APIs below without needing an explicit
‘ResourceManager’ instance; just import and use them as needed.

* Menu:

* Basic Resource Access::
* Resource Extraction::
* “Provider” Interface::


File: setuptools.info,  Node: Basic Resource Access,  Next: Resource Extraction,  Up: ResourceManager API

3.2.7.1 Basic Resource Access
.............................

In the following methods, the ‘package_or_requirement’ argument may be
either a Python package/module name (e.g.  ‘foo.bar’) or a ‘Requirement’
instance.  If it is a package or module name, the named module or
package must be importable (i.e., be in a distribution or directory on
‘sys.path’), and the ‘resource_name’ argument is interpreted relative to
the named package.  (Note that if a module name is used, then the
resource name is relative to the package immediately containing the
named module.  Also, you should not use use a namespace package name,
because a namespace package can be spread across multiple distributions,
and is therefore ambiguous as to which distribution should be searched
for the resource.)

If it is a ‘Requirement’, then the requirement is automatically resolved
(searching the current ‘Environment’ if necessary) and a matching
distribution is added to the ‘WorkingSet’ and ‘sys.path’ if one was not
already present.  (Unless the ‘Requirement’ can’t be satisfied, in which
case an exception is raised.)  The ‘resource_name’ argument is then
interpreted relative to the root of the identified distribution; i.e.
its first path segment will be treated as a peer of the top-level
modules or packages in the distribution.

Note that resource names must be ‘/’-separated paths rooted at the
package, cannot contain relative names like ‘".."’, and cannot be
absolute.  Do `not' use ‘os.path’ routines to manipulate resource paths,
as they are `not' filesystem paths.

‘resource_exists(package_or_requirement, resource_name)’

     Does the named resource exist?  Return ‘True’ or ‘False’
     accordingly.

‘resource_stream(package_or_requirement, resource_name)’

     Return a readable file-like object for the specified resource; it
     may be an actual file, a ‘StringIO’, or some similar object.  The
     stream is in “binary mode”, in the sense that whatever bytes are in
     the resource will be read as-is.

‘resource_string(package_or_requirement, resource_name)’

     Return the specified resource as a string.  The resource is read in
     binary fashion, such that the returned string contains exactly the
     bytes that are stored in the resource.

‘resource_isdir(package_or_requirement, resource_name)’

     Is the named resource a directory?  Return ‘True’ or ‘False’
     accordingly.

‘resource_listdir(package_or_requirement, resource_name)’

     List the contents of the named resource directory, just like
     ‘os.listdir’ except that it works even if the resource is in a
     zipfile.

Note that only ‘resource_exists()’ and ‘resource_isdir()’ are
insensitive as to the resource type.  You cannot use
‘resource_listdir()’ on a file resource, and you can’t use
‘resource_string()’ or ‘resource_stream()’ on directory resources.
Using an inappropriate method for the resource type may result in an
exception or undefined behavior, depending on the platform and
distribution format involved.


File: setuptools.info,  Node: Resource Extraction,  Next: “Provider” Interface,  Prev: Basic Resource Access,  Up: ResourceManager API

3.2.7.2 Resource Extraction
...........................

‘resource_filename(package_or_requirement, resource_name)’

     Sometimes, it is not sufficient to access a resource in string or
     stream form, and a true filesystem filename is needed.  In such
     cases, you can use this method (or module-level function) to obtain
     a filename for a resource.  If the resource is in an archive
     distribution (such as a zipped egg), it will be extracted to a
     cache directory, and the filename within the cache will be
     returned.  If the named resource is a directory, then all resources
     within that directory (including subdirectories) are also
     extracted.  If the named resource is a C extension or “eager
     resource” (see the ‘setuptools’ documentation for details), then
     all C extensions and eager resources are extracted at the same
     time.

     Archived resources are extracted to a cache location that can be
     managed by the following two methods:

‘set_extraction_path(path)’

     Set the base path where resources will be extracted to, if needed.

     If you do not call this routine before any extractions take place,
     the path defaults to the return value of ‘get_default_cache()’.
     (Which is based on the ‘PYTHON_EGG_CACHE’ environment variable,
     with various platform-specific fallbacks.  See that routine’s
     documentation for more details.)

     Resources are extracted to subdirectories of this path based upon
     information given by the resource provider.  You may set this to a
     temporary directory, but then you must call ‘cleanup_resources()’
     to delete the extracted files when done.  There is no guarantee
     that ‘cleanup_resources()’ will be able to remove all extracted
     files.  (On Windows, for example, you can’t unlink .pyd or .dll
     files that are still in use.)

     Note that you may not change the extraction path for a given
     resource manager once resources have been extracted, unless you
     first call ‘cleanup_resources()’.

‘cleanup_resources(force=False)’

     Delete all extracted resource files and directories, returning a
     list of the file and directory names that could not be successfully
     removed.  This function does not have any concurrency protection,
     so it should generally only be called when the extraction path is a
     temporary directory exclusive to a single process.  This method is
     not automatically called; you must call it explicitly or register
     it as an ‘atexit’ function if you wish to ensure cleanup of a
     temporary directory used for extractions.


File: setuptools.info,  Node: “Provider” Interface,  Prev: Resource Extraction,  Up: ResourceManager API

3.2.7.3 “Provider” Interface
............................

If you are implementing an ‘IResourceProvider’ and/or
‘IMetadataProvider’ for a new distribution archive format, you may need
to use the following ‘IResourceManager’ methods to co-ordinate
extraction of resources to the filesystem.  If you’re not implementing
an archive format, however, you have no need to use these methods.
Unlike the other methods listed above, they are `not' available as
top-level functions tied to the global ‘ResourceManager’; you must
therefore have an explicit ‘ResourceManager’ instance to use them.

‘get_cache_path(archive_name, names=())’

     Return absolute location in cache for ‘archive_name’ and ‘names’

     The parent directory of the resulting path will be created if it
     does not already exist.  ‘archive_name’ should be the base filename
     of the enclosing egg (which may not be the name of the enclosing
     zipfile!), including its “.egg” extension.  ‘names’, if provided,
     should be a sequence of path name parts “under” the egg’s
     extraction location.

     This method should only be called by resource providers that need
     to obtain an extraction location, and only for names they intend to
     extract, as it tracks the generated names for possible cleanup
     later.

‘extraction_error()’

     Raise an ‘ExtractionError’ describing the active exception as
     interfering with the extraction process.  You should call this if
     you encounter any OS errors extracting the file to the cache path;
     it will format the operating system exception for you, and add
     other information to the ‘ExtractionError’ instance that may be
     needed by programs that want to wrap or handle extraction errors
     themselves.

‘postprocess(tempname, filename)’

     Perform any platform-specific postprocessing of ‘tempname’.
     Resource providers should call this method ONLY after successfully
     extracting a compressed resource.  They must NOT call it on
     resources that are already in the filesystem.

     ‘tempname’ is the current (temporary) name of the file, and
     ‘filename’ is the name it will be renamed to by the caller after
     this routine returns.


File: setuptools.info,  Node: Metadata API,  Next: Exceptions,  Prev: ResourceManager API,  Up: API Reference

3.2.8 Metadata API
------------------

The metadata API is used to access metadata resources bundled in a
pluggable distribution.  Metadata resources are virtual files or
directories containing information about the distribution, such as might
be used by an extensible application or framework to connect “plugins”.
Like other kinds of resources, metadata resource names are ‘/’-separated
and should not contain ‘..’ or begin with a ‘/’.  You should not use
‘os.path’ routines to manipulate resource paths.

The metadata API is provided by objects implementing the
‘IMetadataProvider’ or ‘IResourceProvider’ interfaces.  ‘Distribution’
objects implement this interface, as do objects returned by the
‘get_provider()’ function:

‘get_provider(package_or_requirement)’

     If a package name is supplied, return an ‘IResourceProvider’ for
     the package.  If a ‘Requirement’ is supplied, resolve it by
     returning a ‘Distribution’ from the current working set (searching
     the current ‘Environment’ if necessary and adding the newly found
     ‘Distribution’ to the working set).  If the named package can’t be
     imported, or the ‘Requirement’ can’t be satisfied, an exception is
     raised.

     NOTE: if you use a package name rather than a ‘Requirement’, the
     object you get back may not be a pluggable distribution, depending
     on the method by which the package was installed.  In particular,
     “development” packages and “single-version externally-managed”
     packages do not have any way to map from a package name to the
     corresponding project’s metadata.  Do not write code that passes a
     package name to ‘get_provider()’ and then tries to retrieve project
     metadata from the returned object.  It may appear to work when the
     named package is in an ‘.egg’ file or directory, but it will fail
     in other installation scenarios.  If you want project metadata, you
     need to ask for a `project', not a package.

* Menu:

* IMetadataProvider Methods::


File: setuptools.info,  Node: IMetadataProvider Methods,  Up: Metadata API

3.2.8.1 ‘IMetadataProvider’ Methods
...................................

The methods provided by objects (such as ‘Distribution’ instances) that
implement the ‘IMetadataProvider’ or ‘IResourceProvider’ interfaces are:

‘has_metadata(name)’

     Does the named metadata resource exist?

‘metadata_isdir(name)’

     Is the named metadata resource a directory?

‘metadata_listdir(name)’

     List of metadata names in the directory (like ‘os.listdir()’)

‘get_metadata(name)’

     Return the named metadata resource as a string.  The data is read
     in binary mode; i.e., the exact bytes of the resource file are
     returned.

‘get_metadata_lines(name)’

     Yield named metadata resource as list of non-blank non-comment
     lines.  This is short for calling
     ‘yield_lines(provider.get_metadata(name))’.  See the section on
     *note yield_lines(): 95. below for more information on the syntax
     it recognizes.

‘run_script(script_name, namespace)’

     Execute the named script in the supplied namespace dictionary.
     Raises ‘ResolutionError’ if there is no script by that name in the
     ‘scripts’ metadata directory.  ‘namespace’ should be a Python
     dictionary, usually a module dictionary if the script is being run
     as a module.


File: setuptools.info,  Node: Exceptions,  Next: Supporting Custom Importers,  Prev: Metadata API,  Up: API Reference

3.2.9 Exceptions
----------------

‘pkg_resources’ provides a simple exception hierarchy for problems that
may occur when processing requests to locate and activate packages:

     ResolutionError
         DistributionNotFound
         VersionConflict
         UnknownExtra

     ExtractionError

‘ResolutionError’

     This class is used as a base class for the other three exceptions,
     so that you can catch all of them with a single “except” clause.
     It is also raised directly for miscellaneous requirement-resolution
     problems like trying to run a script that doesn’t exist in the
     distribution it was requested from.

‘DistributionNotFound’

     A distribution needed to fulfill a requirement could not be found.

‘VersionConflict’

     The requested version of a project conflicts with an
     already-activated version of the same project.

‘UnknownExtra’

     One of the “extras” requested was not recognized by the
     distribution it was requested from.

‘ExtractionError’

     A problem occurred extracting a resource to the Python Egg cache.
     The following attributes are available on instances of this
     exception:

     manager

          The resource manager that raised this exception

     cache_path

          The base directory for resource extraction

     original_error

          The exception instance that caused extraction to fail


File: setuptools.info,  Node: Supporting Custom Importers,  Next: Utility Functions,  Prev: Exceptions,  Up: API Reference

3.2.10 Supporting Custom Importers
----------------------------------

By default, ‘pkg_resources’ supports normal filesystem imports, and
‘zipimport’ importers.  If you wish to use the ‘pkg_resources’ features
with other (PEP 302-compatible) importers or module loaders, you may
need to register various handlers and support functions using these
APIs:

‘register_finder(importer_type, distribution_finder)’

     Register ‘distribution_finder’ to find distributions in ‘sys.path’
     items.  ‘importer_type’ is the type or class of a PEP 302
     “Importer” (‘sys.path’ item handler), and ‘distribution_finder’ is
     a callable that, when passed a path item, the importer instance,
     and an ‘only’ flag, yields ‘Distribution’ instances found under
     that path item.  (The ‘only’ flag, if true, means the finder should
     yield only ‘Distribution’ objects whose ‘location’ is equal to the
     path item provided.)

     See the source of the ‘pkg_resources.find_on_path’ function for an
     example finder function.

‘register_loader_type(loader_type, provider_factory)’

     Register ‘provider_factory’ to make ‘IResourceProvider’ objects for
     ‘loader_type’.  ‘loader_type’ is the type or class of a PEP 302
     ‘module.__loader__’, and ‘provider_factory’ is a function that,
     when passed a module object, returns an *note IResourceProvider:
     8b. for that module, allowing it to be used with the *note
     ResourceManager API: 35.

‘register_namespace_handler(importer_type, namespace_handler)’

     Register ‘namespace_handler’ to declare namespace packages for the
     given ‘importer_type’.  ‘importer_type’ is the type or class of a
     PEP 302 “importer” (sys.path item handler), and ‘namespace_handler’
     is a callable with a signature like this:

          def namespace_handler(importer, path_entry, moduleName, module):
              # return a path_entry to use for child packages

     Namespace handlers are only called if the relevant importer object
     has already agreed that it can handle the relevant path item.  The
     handler should only return a subpath if the module ‘__path__’ does
     not already contain an equivalent subpath.  Otherwise, it should
     return None.

     For an example namespace handler, see the source of the
     ‘pkg_resources.file_ns_handler’ function, which is used for both
     zipfile importing and regular importing.

* Menu:

* IResourceProvider::
* Built-in Resource Providers::


File: setuptools.info,  Node: IResourceProvider,  Next: Built-in Resource Providers,  Up: Supporting Custom Importers

3.2.10.1 IResourceProvider
..........................

‘IResourceProvider’ is an abstract class that documents what methods are
required of objects returned by a ‘provider_factory’ registered with
‘register_loader_type()’.  ‘IResourceProvider’ is a subclass of
‘IMetadataProvider’, so objects that implement this interface must also
implement all of the *note IMetadataProvider Methods: 8c. as well as the
methods shown here.  The ‘manager’ argument to the methods below must be
an object that supports the full *note ResourceManager API: 35.
documented above.

‘get_resource_filename(manager, resource_name)’

     Return a true filesystem path for ‘resource_name’, coordinating the
     extraction with ‘manager’, if the resource must be unpacked to the
     filesystem.

‘get_resource_stream(manager, resource_name)’

     Return a readable file-like object for ‘resource_name’.

‘get_resource_string(manager, resource_name)’

     Return a string containing the contents of ‘resource_name’.

‘has_resource(resource_name)’

     Does the package contain the named resource?

‘resource_isdir(resource_name)’

     Is the named resource a directory?  Return a false value if the
     resource does not exist or is not a directory.

‘resource_listdir(resource_name)’

     Return a list of the contents of the resource directory, ala
     ‘os.listdir()’.  Requesting the contents of a non-existent
     directory may raise an exception.

Note, by the way, that your provider classes need not (and should not)
subclass ‘IResourceProvider’ or ‘IMetadataProvider’!  These classes
exist solely for documentation purposes and do not provide any useful
implementation code.  You may instead wish to subclass one of the *note
built-in resource providers: 97.


File: setuptools.info,  Node: Built-in Resource Providers,  Prev: IResourceProvider,  Up: Supporting Custom Importers

3.2.10.2 Built-in Resource Providers
....................................

‘pkg_resources’ includes several provider classes that are automatically
used where appropriate.  Their inheritance tree looks like this:

     NullProvider
         EggProvider
             DefaultProvider
                 PathMetadata
             ZipProvider
                 EggMetadata
         EmptyProvider
             FileMetadata

‘NullProvider’

     This provider class is just an abstract base that provides for
     common provider behaviors (such as running scripts), given a
     definition for just a few abstract methods.

‘EggProvider’

     This provider class adds in some egg-specific features that are
     common to zipped and unzipped eggs.

‘DefaultProvider’

     This provider class is used for unpacked eggs and “plain old
     Python” filesystem modules.

‘ZipProvider’

     This provider class is used for all zipped modules, whether they
     are eggs or not.

‘EmptyProvider’

     This provider class always returns answers consistent with a
     provider that has no metadata or resources.  ‘Distribution’ objects
     created without a ‘metadata’ argument use an instance of this
     provider class instead.  Since all ‘EmptyProvider’ instances are
     equivalent, there is no need to have more than one instance.
     ‘pkg_resources’ therefore creates a global instance of this class
     under the name ‘empty_provider’, and you may use it if you have
     need of an ‘EmptyProvider’ instance.

‘PathMetadata(path, egg_info)’

     Create an ‘IResourceProvider’ for a filesystem-based distribution,
     where ‘path’ is the filesystem location of the importable modules,
     and ‘egg_info’ is the filesystem location of the distribution’s
     metadata directory.  ‘egg_info’ should usually be the ‘EGG-INFO’
     subdirectory of ‘path’ for an “unpacked egg”, and a
     ‘ProjectName.egg-info’ subdirectory of ‘path’ for a “development
     egg”.  However, other uses are possible for custom purposes.

‘EggMetadata(zipimporter)’

     Create an ‘IResourceProvider’ for a zipfile-based distribution.
     The ‘zipimporter’ should be a ‘zipimport.zipimporter’ instance, and
     may represent a “basket” (a zipfile containing multiple “.egg”
     subdirectories) a specific egg `within' a basket, or a zipfile egg
     (where the zipfile itself is a “.egg”).  It can also be a
     combination, such as a zipfile egg that also contains other eggs.

‘FileMetadata(path_to_pkg_info)’

     Create an ‘IResourceProvider’ that provides exactly one metadata
     resource: ‘PKG-INFO’.  The supplied path should be a distutils
     PKG-INFO file.  This is basically the same as an ‘EmptyProvider’,
     except that requests for ‘PKG-INFO’ will be answered using the
     contents of the designated file.  (This provider is used to wrap
     ‘.egg-info’ files installed by vendor-supplied system packages.)


File: setuptools.info,  Node: Utility Functions,  Prev: Supporting Custom Importers,  Up: API Reference

3.2.11 Utility Functions
------------------------

In addition to its high-level APIs, ‘pkg_resources’ also includes
several generally-useful utility routines.  These routines are used to
implement the high-level APIs, but can also be quite useful by
themselves.

* Menu:

* Parsing Utilities::
* Platform Utilities::
* PEP 302 Utilities::
* File/Path Utilities::
* History::


File: setuptools.info,  Node: Parsing Utilities,  Next: Platform Utilities,  Up: Utility Functions

3.2.11.1 Parsing Utilities
..........................

‘parse_version(version)’

     Parsed a project’s version string as defined by PEP 440.  The
     returned value will be an object that represents the version.
     These objects may be compared to each other and sorted.  The
     sorting algorithm is as defined by PEP 440 with the addition that
     any version which is not a valid PEP 440 version will be considered
     less than any valid PEP 440 version and the invalid versions will
     continue sorting using the original algorithm.

‘yield_lines(strs)’

     Yield non-empty/non-comment lines from a string/unicode or a
     possibly- nested sequence thereof.  If ‘strs’ is an instance of
     ‘basestring’, it is split into lines, and each non-blank,
     non-comment line is yielded after stripping leading and trailing
     whitespace.  (Lines whose first non-blank character is ‘#’ are
     considered comment lines.)

     If ‘strs’ is not an instance of ‘basestring’, it is iterated over,
     and each item is passed recursively to ‘yield_lines()’, so that an
     arbitrarily nested sequence of strings, or sequences of sequences
     of strings can be flattened out to the lines contained therein.  So
     for example, passing a file object or a list of strings to
     ‘yield_lines’ will both work.  (Note that between each string in a
     sequence of strings there is assumed to be an implicit line break,
     so lines cannot bridge two strings in a sequence.)

     This routine is used extensively by ‘pkg_resources’ to parse
     metadata and file formats of various kinds, and most other
     ‘pkg_resources’ parsing functions that yield multiple values will
     use it to break up their input.  However, this routine is
     idempotent, so calling ‘yield_lines()’ on the output of another
     call to ‘yield_lines()’ is completely harmless.

‘split_sections(strs)’

     Split a string (or possibly-nested iterable thereof), yielding
     ‘(section, content)’ pairs found using an ‘.ini’-like syntax.  Each
     ‘section’ is a whitespace-stripped version of the section name
     (“‘[section]’”) and each ‘content’ is a list of stripped lines
     excluding blank lines and comment-only lines.  If there are any
     non-blank, non-comment lines before the first section header,
     they’re yielded in a first ‘section’ of ‘None’.

     This routine uses ‘yield_lines()’ as its front end, so you can pass
     in anything that ‘yield_lines()’ accepts, such as an open text
     file, string, or sequence of strings.  ‘ValueError’ is raised if a
     malformed section header is found (i.e.  a line starting with ‘[’
     but not ending with ‘]’).

     Note that this simplistic parser assumes that any line whose first
     nonblank character is ‘[’ is a section heading, so it can’t support
     .ini format variations that allow ‘[’ as the first nonblank
     character on other lines.

‘safe_name(name)’

     Return a “safe” form of a project’s name, suitable for use in a
     ‘Requirement’ string, as a distribution name, or a PyPI project
     name.  All non-alphanumeric runs are condensed to single “-”
     characters, such that a name like “The $$$ Tree” becomes
     “The-Tree”.  Note that if you are generating a filename from this
     value you should combine it with a call to ‘to_filename()’ so all
     dashes (“-“) are replaced by underscores (“_”).  See
     ‘to_filename()’.

‘safe_version(version)’

     This will return the normalized form of any PEP 440 version.  If
     the version string is not PEP 440 compatible, this function behaves
     similar to ‘safe_name()’ except that spaces in the input become
     dots, and dots are allowed to exist in the output.  As with
     ‘safe_name()’, if you are generating a filename from this you
     should replace any “-” characters in the output with underscores.

‘safe_extra(extra)’

     Return a “safe” form of an extra’s name, suitable for use in a
     requirement string or a setup script’s ‘extras_require’ keyword.
     This routine is similar to ‘safe_name()’ except that
     non-alphanumeric runs are replaced by a single underbar (‘_’), and
     the result is lowercased.

‘to_filename(name_or_version)’

     Escape a name or version string so it can be used in a
     dash-separated filename (or ‘#egg=name-version’ tag) without
     ambiguity.  You should only pass in values that were returned by
     ‘safe_name()’ or ‘safe_version()’.


File: setuptools.info,  Node: Platform Utilities,  Next: PEP 302 Utilities,  Prev: Parsing Utilities,  Up: Utility Functions

3.2.11.2 Platform Utilities
...........................

‘get_build_platform()’

     Return this platform’s identifier string.  For Windows, the return
     value is ‘"win32"’, and for macOS it is a string of the form
     ‘"macosx-10.4-ppc"’.  All other platforms return the same
     uname-based string that the ‘distutils.util.get_platform()’
     function returns.  This string is the minimum platform version
     required by distributions built on the local machine.  (Backward
     compatibility note: setuptools versions prior to 0.6b1 called this
     function ‘get_platform()’, and the function is still available
     under that name for backward compatibility reasons.)

‘get_supported_platform()’ (New in 0.6b1)

     This is the similar to ‘get_build_platform()’, but is the maximum
     platform version that the local machine supports.  You will usually
     want to use this value as the ‘provided’ argument to the
     ‘compatible_platforms()’ function.

‘compatible_platforms(provided, required)’

     Return true if a distribution built on the ‘provided’ platform may
     be used on the ‘required’ platform.  If either platform value is
     ‘None’, it is considered a wildcard, and the platforms are
     therefore compatible.  Likewise, if the platform strings are equal,
     they’re also considered compatible, and ‘True’ is returned.
     Currently, the only non-equal platform strings that are considered
     compatible are macOS platform strings with the same hardware type
     (e.g.  ‘ppc’) and major version (e.g.  ‘10’) with the ‘provided’
     platform’s minor version being less than or equal to the ‘required’
     platform’s minor version.

‘get_default_cache()’

     Determine the default cache location for extracting resources from
     zipped eggs.  This routine returns the ‘PYTHON_EGG_CACHE’
     environment variable, if set.  Otherwise, on Windows, it returns a
     “Python-Eggs” subdirectory of the user’s “Application Data”
     directory.  On all other systems, it returns
     ‘os.path.expanduser("~/.python-eggs")’ if ‘PYTHON_EGG_CACHE’ is not
     set.


File: setuptools.info,  Node: PEP 302 Utilities,  Next: File/Path Utilities,  Prev: Platform Utilities,  Up: Utility Functions

3.2.11.3 PEP 302 Utilities
..........................

‘get_importer(path_item)’

     A deprecated alias for ‘pkgutil.get_importer()’


File: setuptools.info,  Node: File/Path Utilities,  Next: History,  Prev: PEP 302 Utilities,  Up: Utility Functions

3.2.11.4 File/Path Utilities
............................

‘ensure_directory(path)’

     Ensure that the parent directory (‘os.path.dirname’) of ‘path’
     actually exists, using ‘os.makedirs()’ if necessary.

‘normalize_path(path)’

     Return a “normalized” version of ‘path’, such that two paths
     represent the same filesystem location if they have equal
     ‘normalized_path()’ values.  Specifically, this is a shortcut for
     calling ‘os.path.realpath’ and ‘os.path.normcase’ on ‘path’.
     Unfortunately, on certain platforms (notably Cygwin and macOS) the
     ‘normcase’ function does not accurately reflect the platform’s
     case-sensitivity, so there is always the possibility of two
     apparently-different paths being equal on such platforms.


File: setuptools.info,  Node: History,  Prev: File/Path Utilities,  Up: Utility Functions

3.2.11.5 History
................

0.6c9

        * Fix ‘resource_listdir('')’ always returning an empty list for
          zipped eggs.

0.6c7

        * Fix package precedence problem where single-version eggs
          installed in ‘site-packages’ would take precedence over ‘.egg’
          files (or directories) installed in ‘site-packages’.

0.6c6

        * Fix extracted C extensions not having executable permissions
          under Cygwin.

        * Allow ‘.egg-link’ files to contain relative paths.

        * Fix cache dir defaults on Windows when multiple environment
          vars are needed to construct a path.

0.6c4

        * Fix “dev” versions being considered newer than release
          candidates.

0.6c3

        * Python 2.5 compatibility fixes.

0.6c2

        * Fix a problem with eggs specified directly on ‘PYTHONPATH’ on
          case-insensitive filesystems possibly not showing up in the
          default working set, due to differing normalizations of
          ‘sys.path’ entries.

0.6b3

        * Fixed a duplicate path insertion problem on case-insensitive
          filesystems.

0.6b1

        * Split ‘get_platform()’ into ‘get_supported_platform()’ and
          ‘get_build_platform()’ to work around a Mac versioning problem
          that caused the behavior of ‘compatible_platforms()’ to be
          platform specific.

        * Fix entry point parsing when a standalone module name has
          whitespace between it and the extras.

0.6a11

        * Added ‘ExtractionError’ and
          ‘ResourceManager.extraction_error()’ so that cache permission
          problems get a more user-friendly explanation of the problem,
          and so that programs can catch and handle extraction errors if
          they need to.

0.6a10

        * Added the ‘extras’ attribute to ‘Distribution’, the
          ‘find_plugins()’ method to ‘WorkingSet’, and the ‘__add__()’
          and ‘__iadd__()’ methods to ‘Environment’.

        * ‘safe_name()’ now allows dots in project names.

        * There is a new ‘to_filename()’ function that escapes project
          names and versions for safe use in constructing egg filenames
          from a Distribution object’s metadata.

        * Added ‘Distribution.clone()’ method, and keyword argument
          support to other ‘Distribution’ constructors.

        * Added the ‘DEVELOP_DIST’ precedence, and automatically assign
          it to eggs using ‘.egg-info’ format.

0.6a9

        * Don’t raise an error when an invalid (unfinished) distribution
          is found unless absolutely necessary.  Warn about skipping
          invalid/unfinished eggs when building an Environment.

        * Added support for ‘.egg-info’ files or directories with
          version/platform information embedded in the filename, so that
          system packagers have the option of including ‘PKG-INFO’ files
          to indicate the presence of a system-installed egg, without
          needing to use ‘.egg’ directories, zipfiles, or ‘.pth’
          manipulation.

        * Changed ‘parse_version()’ to remove dashes before pre-release
          tags, so that ‘0.2-rc1’ is considered an `older' version than
          ‘0.2’, and is equal to ‘0.2rc1’.  The idea that a dash
          `always' meant a post-release version was highly non-intuitive
          to setuptools users and Python developers, who seem to want to
          use ‘-rc’ version numbers a lot.

0.6a8

        * Fixed a problem with ‘WorkingSet.resolve()’ that prevented
          version conflicts from being detected at runtime.

        * Improved runtime conflict warning message to identify a line
          in the user’s program, rather than flagging the ‘warn()’ call
          in ‘pkg_resources’.

        * Avoid giving runtime conflict warnings for namespace packages,
          even if they were declared by a different package than the one
          currently being activated.

        * Fix path insertion algorithm for case-insensitive filesystems.

        * Fixed a problem with nested namespace packages (e.g.
          ‘peak.util’) not being set as an attribute of their parent
          package.

0.6a6

        * Activated distributions are now inserted in ‘sys.path’ (and
          the working set) just before the directory that contains them,
          instead of at the end.  This allows e.g.  eggs in
          ‘site-packages’ to override unmanaged modules in the same
          location, and allows eggs found earlier on ‘sys.path’ to
          override ones found later.

        * When a distribution is activated, it now checks whether any
          contained non-namespace modules have already been imported and
          issues a warning if a conflicting module has already been
          imported.

        * Changed dependency processing so that it’s breadth-first,
          allowing a depender’s preferences to override those of a
          dependee, to prevent conflicts when a lower version is
          acceptable to the dependee, but not the depender.

        * Fixed a problem extracting zipped files on Windows, when the
          egg in question has had changed contents but still has the
          same version number.

0.6a4

        * Fix a bug in ‘WorkingSet.resolve()’ that was introduced in
          0.6a3.

0.6a3

        * Added ‘safe_extra()’ parsing utility routine, and use it for
          Requirement, EntryPoint, and Distribution objects’ extras
          handling.

0.6a1

        * Enhanced performance of ‘require()’ and related operations
          when all requirements are already in the working set, and
          enhanced performance of directory scanning for distributions.

        * Fixed some problems using ‘pkg_resources’ w/PEP 302 loaders
          other than ‘zipimport’, and the previously-broken “eager
          resource” support.

        * Fixed ‘pkg_resources.resource_exists()’ not working correctly,
          along with some other resource API bugs.

        * Many API changes and enhancements:

             * Added ‘EntryPoint’, ‘get_entry_map’, ‘load_entry_point’,
               and ‘get_entry_info’ APIs for dynamic plugin discovery.

             * ‘list_resources’ is now ‘resource_listdir’ (and it
               actually works)

             * Resource API functions like ‘resource_string()’ that
               accepted a package name and resource name, will now also
               accept a ‘Requirement’ object in place of the package
               name (to allow access to non-package data files in an
               egg).

             * ‘get_provider()’ will now accept a ‘Requirement’ instance
               or a module name.  If it is given a ‘Requirement’, it
               will return a corresponding ‘Distribution’ (by calling
               ‘require()’ if a suitable distribution isn’t already in
               the working set), rather than returning a metadata and
               resource provider for a specific module.  (The difference
               is in how resource paths are interpreted; supplying a
               module name means resources path will be module-relative,
               rather than relative to the distribution’s root.)

             * ‘Distribution’ objects now implement the
               ‘IResourceProvider’ and ‘IMetadataProvider’ interfaces,
               so you don’t need to reference the (no longer available)
               ‘metadata’ attribute to get at these interfaces.

             * ‘Distribution’ and ‘Requirement’ both have a
               ‘project_name’ attribute for the project name they refer
               to.  (Previously these were ‘name’ and ‘distname’
               attributes.)

             * The ‘path’ attribute of ‘Distribution’ objects is now
               ‘location’, because it isn’t necessarily a filesystem
               path (and hasn’t been for some time now).  The ‘location’
               of ‘Distribution’ objects in the filesystem should always
               be normalized using ‘pkg_resources.normalize_path()’; all
               of the setuptools’ code that generates distributions from
               the filesystem (including ‘Distribution.from_filename()’)
               ensure this invariant, but if you use a more generic API
               like ‘Distribution()’ or ‘Distribution.from_location()’
               you should take care that you don’t create a distribution
               with an un-normalized filesystem path.

             * ‘Distribution’ objects now have an ‘as_requirement()’
               method that returns a ‘Requirement’ for the
               distribution’s project name and version.

             * Distribution objects no longer have an ‘installed_on()’
               method, and the ‘install_on()’ method is now ‘activate()’
               (but may go away altogether soon).  The ‘depends()’
               method has also been renamed to ‘requires()’, and
               ‘InvalidOption’ is now ‘UnknownExtra’.

             * ‘find_distributions()’ now takes an additional argument
               called ‘only’, that tells it to only yield distributions
               whose location is the passed-in path.  (It defaults to
               False, so that the default behavior is unchanged.)

             * ‘AvailableDistributions’ is now called ‘Environment’, and
               the ‘get()’, ‘__len__()’, and ‘__contains__()’ methods
               were removed, because they weren’t particularly useful.
               ‘__getitem__()’ no longer raises ‘KeyError’; it just
               returns an empty list if there are no distributions for
               the named project.

             * The ‘resolve()’ method of ‘Environment’ is now a method
               of ‘WorkingSet’ instead, and the ‘best_match()’ method
               now uses a working set instead of a path list as its
               second argument.

             * There is a new ‘pkg_resources.add_activation_listener()’
               API that lets you register a callback for notifications
               about distributions added to ‘sys.path’ (including the
               distributions already on it).  This is basically a hook
               for extensible applications and frameworks to be able to
               search for plugin metadata in distributions added at
               runtime.

0.5a13

        * Fixed a bug in resource extraction from nested packages in a
          zipped egg.

0.5a12

        * Updated extraction/cache mechanism for zipped resources to
          avoid inter- process and inter-thread races during extraction.
          The default cache location can now be set via the
          ‘PYTHON_EGGS_CACHE’ environment variable, and the default
          Windows cache is now a ‘Python-Eggs’ subdirectory of the
          current user’s “Application Data” directory, if the
          ‘PYTHON_EGGS_CACHE’ variable isn’t set.

0.5a10

        * Fix a problem with ‘pkg_resources’ being confused by
          non-existent eggs on ‘sys.path’ (e.g.  if a user deletes an
          egg without removing it from the ‘easy-install.pth’ file).

        * Fix a problem with “basket” support in ‘pkg_resources’, where
          egg-finding never actually went inside ‘.egg’ files.

        * Made ‘pkg_resources’ import the module you request resources
          from, if it’s not already imported.

0.5a4

        * ‘pkg_resources.AvailableDistributions.resolve()’ and related
          methods now accept an ‘installer’ argument: a callable taking
          one argument, a ‘Requirement’ instance.  The callable must
          return a ‘Distribution’ object, or ‘None’ if no distribution
          is found.  This feature is used by EasyInstall to resolve
          dependencies by recursively invoking itself.

0.4a4

        * Fix problems with ‘resource_listdir()’, ‘resource_isdir()’ and
          resource directory extraction for zipped eggs.

0.4a3

        * Fixed scripts not being able to see a ‘__file__’ variable in
          ‘__main__’

        * Fixed a problem with ‘resource_isdir()’ implementation that
          was introduced in 0.4a2.

0.4a1

        * Fixed a bug in requirements processing for exact versions
          (i.e.  ‘==’ and ‘!=’) when only one condition was included.

        * Added ‘safe_name()’ and ‘safe_version()’ APIs to clean up
          handling of arbitrary distribution names and versions found on
          PyPI.

0.3a4

        * ‘pkg_resources’ now supports resource directories, not just
          the resources in them.  In particular, there are
          ‘resource_listdir()’ and ‘resource_isdir()’ APIs.

        * ‘pkg_resources’ now supports “egg baskets” – .egg zipfiles
          which contain multiple distributions in subdirectories whose
          names end with ‘.egg’.  Having such a “basket” in a directory
          on ‘sys.path’ is equivalent to having the individual eggs in
          that directory, but the contained eggs can be individually
          added (or not) to ‘sys.path’.  Currently, however, there is no
          automated way to create baskets.

        * Namespace package manipulation is now protected by the Python
          import lock.

0.3a1

        * Initial release.


File: setuptools.info,  Node: Keywords,  Next: Roadmap,  Prev: Package Discovery and Resource Access using pkg_resources,  Up: Top

4 Keywords
**********

‘name’

     A string specifying the name of the package.

‘version’

     A string specifying the version number of the package.

‘description’

     A string describing the package in a single line.

‘long_description’

     A string providing a longer description of the package.

‘long_description_content_type’

     A string specifying the content type is used for the
     ‘long_description’ (e.g.  ‘text/markdown’)

‘author’

     A string specifying the author of the package.

‘author_email’

     A string specifying the email address of the package author.

‘maintainer’

     A string specifying the name of the current maintainer, if
     different from the author.  Note that if the maintainer is
     provided, setuptools will use it as the author in ‘PKG-INFO’.

‘maintainer_email’

     A string specifying the email address of the current maintainer, if
     different from the author.

‘url’

     A string specifying the URL for the package homepage.

‘download_url’

     A string specifying the URL to download the package.

‘packages’

     A list of strings specifying the packages that setuptools will
     manipulate.

‘py_modules’

     A list of strings specifying the modules that setuptools will
     manipulate.

‘scripts’

     A list of strings specifying the standalone script files to be
     built and installed.

‘ext_package’

     A string specifying the base package name for the extensions
     provided by this package.

‘ext_modules’

     A list of instances of ‘setuptools.Extension’ providing the list of
     Python extensions to be built.

‘classifiers’

     A list of strings describing the categories for the package.

‘distclass’

     A subclass of ‘Distribution’ to use.

‘script_name’

     A string specifying the name of the setup.py script – defaults to
     ‘sys.argv[0]’

‘script_args’

     A list of strings defining the arguments to supply to the setup
     script.

‘options’

     A dictionary providing the default options for the setup script.

‘license’

     A string specifying the license of the package.

‘keywords’

     A list of strings or a comma-separated string providing descriptive
     meta-data.  See: PEP 0314(1).

‘platforms’

     A list of strings or comma-separated string.

‘cmdclass’

     A dictionary providing a mapping of command names to ‘Command’
     subclasses.

‘data_files’

          Warning: ‘data_files’ is deprecated.  It does not work with
          wheels, so it should be avoided.

     A list of strings specifying the data files to install.

‘package_dir’

     A dictionary providing a mapping of package to directory names.

‘requires’

          Warning: ‘requires’ is superseded by ‘install_requires’ and
          should not be used anymore.

‘obsoletes’

          Warning: ‘obsoletes’ is currently ignored by ‘pip’.

     List of strings describing packages which this package renders
     obsolete, meaning that the two projects should not be installed at
     the same time.

     Version declarations can be supplied.  Version numbers must be in
     the format specified in Version specifiers (e.g.  ‘foo (<3.0)’).

     This field may be followed by an environment marker after a
     semicolon (e.g.  ‘foo; os_name == "posix"’)

     The most common use of this field will be in case a project name
     changes, e.g.  Gorgon 2.3 gets subsumed into Torqued Python 1.0.
     When you install Torqued Python, the Gorgon distribution should be
     removed.

‘provides’

          Warning: ‘provides’ is currently ignored by ‘pip’.

     List of strings describing package- and virtual package names
     contained within this package.

     A package may provide additional names, e.g.  to indicate that
     multiple projects have been bundled together.  For instance, source
     distributions of the ZODB project have historically included the
     transaction project, which is now available as a separate
     distribution.  Installing such a source distribution satisfies
     requirements for both ZODB and transaction.

     A package may also provide a “virtual” project name, which does not
     correspond to any separately-distributed project: such a name might
     be used to indicate an abstract capability which could be supplied
     by one of multiple projects.  E.g., multiple projects might supply
     RDBMS bindings for use by a given ORM: each project might declare
     that it provides ORM-bindings, allowing other projects to depend
     only on having at most one of them installed.

     A version declaration may be supplied and must follow the rules
     described in Version specifiers.  The distribution’s version number
     will be implied if none is specified (e.g.  ‘foo (<3.0)’).

     Each package may be followed by an environment marker after a
     semicolon (e.g.  ‘foo; os_name == "posix"’).

‘include_package_data’

     If set to ‘True’, this tells ‘setuptools’ to automatically include
     any data files it finds inside your package directories that are
     specified by your ‘MANIFEST.in’ file.  For more information, see
     the section on *note Including Data Files: 12.

‘exclude_package_data’

     A dictionary mapping package names to lists of glob patterns that
     should be `excluded' from your package directories.  You can use
     this to trim back any excess files included by
     ‘include_package_data’.  For a complete description and examples,
     see the section on *note Including Data Files: 12.

‘package_data’

     A dictionary mapping package names to lists of glob patterns.  For
     a complete description and examples, see the section on *note
     Including Data Files: 12.  You do not need to use this option if
     you are using ‘include_package_data’, unless you need to add e.g.
     files that are generated by your setup script and build process.
     (And are therefore not in source control or are files that you
     don’t want to include in your source distribution.)

‘zip_safe’

     A boolean (True or False) flag specifying whether the project can
     be safely installed and run from a zip file.  If this argument is
     not supplied, the ‘bdist_egg’ command will have to analyze all of
     your project’s contents for possible problems each time it builds
     an egg.

‘install_requires’

     A string or list of strings specifying what other distributions
     need to be installed when this one is.  See the section on *note
     Declaring required dependency: 2b. for details and examples of the
     format of this argument.

‘entry_points’

     A dictionary mapping entry point group names to strings or lists of
     strings defining the entry points.  Entry points are used to
     support dynamic discovery of services or plugins provided by a
     project.  See *note Advertising Behavior: 25. for details and
     examples of the format of this argument.  In addition, this keyword
     is used to support *note Automatic Script Creation: 21.

‘extras_require’

     A dictionary mapping names of “extras” (optional features of your
     project) to strings or lists of strings specifying what other
     distributions must be installed to support those features.  See the
     section on *note Declaring required dependency: 2b. for details and
     examples of the format of this argument.

‘python_requires’

     A string corresponding to a version specifier (as defined in PEP
     440) for the Python version, used to specify the Requires-Python
     defined in PEP 345.

‘setup_requires’

          Warning: Using ‘setup_requires’ is discouraged in favor of
          PEP-518(2)

     A string or list of strings specifying what other distributions
     need to be present in order for the `setup script' to run.
     ‘setuptools’ will attempt to obtain these (even going so far as to
     download them using ‘EasyInstall’) before processing the rest of
     the setup script or commands.  This argument is needed if you are
     using distutils extensions as part of your build process; for
     example, extensions that process setup() arguments and turn them
     into EGG-INFO metadata files.

     (Note: projects listed in ‘setup_requires’ will NOT be
     automatically installed on the system where the setup script is
     being run.  They are simply downloaded to the ./.eggs directory if
     they’re not locally available already.  If you want them to be
     installed, as well as being available when the setup script is run,
     you should add them to ‘install_requires’ `and' ‘setup_requires’.)

‘dependency_links’

          Warning: ‘dependency_links’ is deprecated.  It is not
          supported anymore by pip.

     A list of strings naming URLs to be searched when satisfying
     dependencies.  These links will be used if needed to install
     packages specified by ‘setup_requires’ or ‘tests_require’.  They
     will also be written into the egg’s metadata for use by tools like
     EasyInstall to use when installing an ‘.egg’ file.

‘namespace_packages’

     A list of strings naming the project’s “namespace packages”.  A
     namespace package is a package that may be split across multiple
     project distributions.  For example, Zope 3’s ‘zope’ package is a
     namespace package, because subpackages like ‘zope.interface’ and
     ‘zope.publisher’ may be distributed separately.  The egg runtime
     system can automatically merge such subpackages into a single
     parent package at runtime, as long as you declare them in each
     project that contains any subpackages of the namespace package, and
     as long as the namespace package’s ‘__init__.py’ does not contain
     any code other than a namespace declaration.  See the section on
     *note Using find_namespace; or find_namespace_packages: 1c. for
     more information.

‘test_suite’

     A string naming a ‘unittest.TestCase’ subclass (or a package or
     module containing one or more of them, or a method of such a
     subclass), or naming a function that can be called with no
     arguments and returns a ‘unittest.TestSuite’.  If the named suite
     is a module, and the module has an ‘additional_tests()’ function,
     it is called and the results are added to the tests to be run.  If
     the named suite is a package, any submodules and subpackages are
     recursively added to the overall test suite.

     Specifying this argument enables use of the *note test - Build
     package and run a unittest suite: 56. command to run the specified
     test suite, e.g.  via ‘setup.py test’.  See the section on the
     *note test - Build package and run a unittest suite: 56. command
     below for more details.

     New in 41.5.0: Deprecated the test command.

‘tests_require’

     If your project’s tests need one or more additional packages
     besides those needed to install it, you can use this option to
     specify them.  It should be a string or list of strings specifying
     what other distributions need to be present for the package’s tests
     to run.  When you run the ‘test’ command, ‘setuptools’ will attempt
     to obtain these (even going so far as to download them using
     ‘EasyInstall’).  Note that these required projects will `not' be
     installed on the system where the tests are run, but only
     downloaded to the project’s setup directory if they’re not already
     installed locally.

     New in 41.5.0: Deprecated the test command.

‘test_loader’

     If you would like to use a different way of finding tests to run
     than what setuptools normally uses, you can specify a module name
     and class name in this argument.  The named class must be
     instantiable with no arguments, and its instances must support the
     ‘loadTestsFromNames()’ method as defined in the Python ‘unittest’
     module’s ‘TestLoader’ class.  Setuptools will pass only one test
     “name” in the ‘names’ argument: the value supplied for the
     ‘test_suite’ argument.  The loader you specify may interpret this
     string in any way it likes, as there are no restrictions on what
     may be contained in a ‘test_suite’ string.

     The module name and class name must be separated by a ‘:’.  The
     default value of this argument is
     ‘"setuptools.command.test:ScanningLoader"’.  If you want to use the
     default ‘unittest’ behavior, you can specify
     ‘"unittest:TestLoader"’ as your ‘test_loader’ argument instead.
     This will prevent automatic scanning of submodules and subpackages.

     The module and class you specify here may be contained in another
     package, as long as you use the ‘tests_require’ option to ensure
     that the package containing the loader class is available when the
     ‘test’ command is run.

     New in 41.5.0: Deprecated the test command.

‘eager_resources’

     A list of strings naming resources that should be extracted
     together, if any of them is needed, or if any C extensions included
     in the project are imported.  This argument is only useful if the
     project will be installed as a zipfile, and there is a need to have
     all of the listed resources be extracted to the filesystem `as a
     unit'.  Resources listed here should be ‘/’-separated paths,
     relative to the source root, so to list a resource ‘foo.png’ in
     package ‘bar.baz’, you would include the string ‘bar/baz/foo.png’
     in this argument.

     If you only need to obtain resources one at a time, or you don’t
     have any C extensions that access other files in the project (such
     as data files or shared libraries), you probably do NOT need this
     argument and shouldn’t mess with it.  For more details on how this
     argument works, see the section below on *note Automatic Resource
     Extraction: 58.

‘use_2to3’

     Convert the source code from Python 2 to Python 3 with 2to3 during
     the build process.  See *note Supporting both Python 2 and Python 3
     with Setuptools: 59. for more details.

‘convert_2to3_doctests’

     List of doctest source files that need to be converted with 2to3.
     See *note Supporting both Python 2 and Python 3 with Setuptools:
     59. for more details.

‘use_2to3_fixers’

     A list of modules to search for additional fixers to be used during
     the 2to3 conversion.  See *note Supporting both Python 2 and Python
     3 with Setuptools: 59. for more details.

‘use_2to3_exclude_fixers’

     List of fixer names to be skipped.

‘project_urls’

     An arbitrary map of URL names to hyperlinks, allowing more
     extensible documentation of where various resources can be found
     than the simple ‘url’ and ‘download_url’ options provide.

   ---------- Footnotes ----------

   (1) https://www.python.org/dev/peps/pep-0314/

   (2) http://www.python.org/dev/peps/pep-0518/


File: setuptools.info,  Node: Roadmap,  Next: Building and Distributing Packages with Setuptools<2>,  Prev: Keywords,  Up: Top

5 Roadmap
*********

Setuptools maintains a series of milestones(1) to track a roadmap of
large-scale goals.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/milestones


File: setuptools.info,  Node: Building and Distributing Packages with Setuptools<2>,  Next: Development on Setuptools,  Prev: Roadmap,  Up: Top

6 Building and Distributing Packages with Setuptools
****************************************************

‘Setuptools’ is a collection of enhancements to the Python ‘distutils’
that allow developers to more easily build and distribute Python
packages, especially ones that have dependencies on other packages.

Packages built and distributed using ‘setuptools’ look to the user like
ordinary Python packages based on the ‘distutils’.

Feature Highlights:

   * Create Python Eggs(1) - a single-file importable distribution
     format

   * Enhanced support for accessing data files hosted in zipped
     packages.

   * Automatically include all packages in your source tree, without
     listing them individually in setup.py

   * Automatically include all relevant files in your source
     distributions, without needing to create a ‘MANIFEST.in’ file, and
     without having to force regeneration of the ‘MANIFEST’ file when
     your source tree changes.

   * Automatically generate wrapper scripts or Windows (console and GUI)
     .exe files for any number of “main” functions in your project.
     (Note: this is not a py2exe replacement; the .exe files rely on the
     local Python installation.)

   * Transparent Cython support, so that your setup.py can list ‘.pyx’
     files and still work even when the end-user doesn’t have Cython
     installed (as long as you include the Cython-generated C in your
     source distribution)

   * Command aliases - create project-specific, per-user, or site-wide
     shortcut names for commonly used commands and options

   * Deploy your project in “development mode”, such that it’s available
     on ‘sys.path’, yet can still be edited directly from its source
     checkout.

   * Easily extend the distutils with new commands or ‘setup()’
     arguments, and distribute/reuse your extensions for multiple
     projects, without copying code.

   * Create extensible applications and frameworks that automatically
     discover extensions, using simple “entry points” declared in a
     project’s setup script.

   * Full support for PEP 420 via ‘find_namespace_packages()’, which is
     also backwards compatible to the existing ‘find_packages()’ for
     Python >= 3.3.

* Menu:

* Developer’s Guide::

   ---------- Footnotes ----------

   (1) http://peak.telecommunity.com/DevCenter/PythonEggs


File: setuptools.info,  Node: Developer’s Guide,  Up: Building and Distributing Packages with Setuptools<2>

6.1 Developer’s Guide
=====================

* Menu:

* TRANSITIONAL NOTE::


File: setuptools.info,  Node: TRANSITIONAL NOTE,  Up: Developer’s Guide

6.1.1 TRANSITIONAL NOTE
-----------------------

Setuptools automatically calls ‘declare_namespace()’ for you at runtime,
but future versions may `not'.  This is because the automatic
declaration feature has some negative side effects, such as needing to
import all namespace packages during the initialization of the
‘pkg_resources’ runtime, and also the need for ‘pkg_resources’ to be
explicitly imported before any namespace packages work at all.  In some
future releases, you’ll be responsible for including your own
declaration lines, and the automatic declaration feature will be dropped
to get rid of the negative side effects.

During the remainder of the current development cycle, therefore,
setuptools will warn you about missing ‘declare_namespace()’ calls in
your ‘__init__.py’ files, and you should correct these as soon as
possible before the compatibility support is removed.  Namespace
packages without declaration lines will not work correctly once a user
has upgraded to a later version, so it’s important that you make this
change now in order to avoid having your code break in the field.  Our
apologies for the inconvenience, and thank you for your patience.

* Menu:

* setup.cfg-only projects: setup cfg-only projects.
* Configuration API::
* Mailing List and Bug Tracker::


File: setuptools.info,  Node: setup cfg-only projects,  Next: Configuration API,  Up: TRANSITIONAL NOTE

6.1.1.1 setup.cfg-only projects
...............................

New in version 40.9.0.

If ‘setup.py’ is missing from the project directory when a PEP 517(1)
build is invoked, ‘setuptools’ emulates a dummy ‘setup.py’ file
containing only a ‘setuptools.setup()’ call.

     Note: PEP 517(2) doesn’t support editable installs so this is
     currently incompatible with ‘pip install -e .’, as PEP 517(3) does
     not support editable installs.

This means that you can have a Python project with all build
configuration specified in ‘setup.cfg’, without a ‘setup.py’ file, if
you `can rely on' your project always being built by a PEP 517(4)/ PEP
518(5) compatible frontend.

To use this feature:

   * Specify build requirements and PEP 517(6) build backend in
     ‘pyproject.toml’.  For example:

          [build-system]
          requires = [
            "setuptools >= 40.9.0",
            "wheel",
          ]
          build-backend = "setuptools.build_meta"

   * Use a PEP 517(7) compatible build frontend, such as ‘pip >= 19’ or
     ‘pep517’.

          Warning: As PEP 517(8) is new, support is not universal, and
          frontends that do support it may still have bugs.  For
          compatibility, you may want to put a ‘setup.py’ file
          containing only a ‘setuptools.setup()’ invocation.

   ---------- Footnotes ----------

   (1) https://www.python.org/dev/peps/pep-0517

   (2) https://www.python.org/dev/peps/pep-0517

   (3) https://www.python.org/dev/peps/pep-0517

   (4) https://www.python.org/dev/peps/pep-0517

   (5) https://www.python.org/dev/peps/pep-0518

   (6) https://www.python.org/dev/peps/pep-0517

   (7) https://www.python.org/dev/peps/pep-0517

   (8) https://www.python.org/dev/peps/pep-0517


File: setuptools.info,  Node: Configuration API,  Next: Mailing List and Bug Tracker,  Prev: setup cfg-only projects,  Up: TRANSITIONAL NOTE

6.1.1.2 Configuration API
.........................

Some automation tools may wish to access data from a configuration file.

‘Setuptools’ exposes a ‘read_configuration()’ function for parsing
‘metadata’ and ‘options’ sections into a dictionary.

     from setuptools.config import read_configuration

     conf_dict = read_configuration("/home/user/dev/package/setup.cfg")

By default, ‘read_configuration()’ will read only the file provided in
the first argument.  To include values from other configuration files
which could be in various places, set the ‘find_others’ keyword argument
to ‘True’.

If you have only a configuration file but not the whole package, you can
still try to get data out of it with the help of the
‘ignore_option_errors’ keyword argument.  When it is set to ‘True’, all
options with errors possibly produced by directives, such as ‘attr:’ and
others, will be silently ignored.  As a consequence, the resulting
dictionary will include no such options.


File: setuptools.info,  Node: Mailing List and Bug Tracker,  Prev: Configuration API,  Up: TRANSITIONAL NOTE

6.1.1.3 Mailing List and Bug Tracker
....................................

Please use the distutils-sig mailing list(1) for questions and
discussion about setuptools, and the setuptools bug tracker(2) ONLY for
issues you have confirmed via the list are actual bugs, and which you
have reduced to a minimal set of steps to reproduce.

   ---------- Footnotes ----------

   (1) http://mail.python.org/pipermail/distutils-sig/

   (2) https://github.com/pypa/setuptools/


File: setuptools.info,  Node: Development on Setuptools,  Next: Guides on backward compatibility & deprecated practice,  Prev: Building and Distributing Packages with Setuptools<2>,  Up: Top

7 Development on Setuptools
***************************

Setuptools is maintained by the Python community under the Python
Packaging Authority (PyPA) and led by Jason R. Coombs.

This document describes the process by which Setuptools is developed.
This document assumes the reader has some passing familiarity with
`using' setuptools, the ‘pkg_resources’ module, and pip.  It does not
attempt to explain basic concepts like inter-project dependencies, nor
does it contain detailed lexical syntax for most file formats.  Neither
does it explain concepts like “namespace packages” or “resources” in any
detail, as all of these subjects are covered at length in the setuptools
developer’s guide and the ‘pkg_resources’ reference manual.

Instead, this is `internal' documentation for how those concepts and
features are `implemented' in concrete terms.  It is intended for people
who are working on the setuptools code base, who want to be able to
troubleshoot setuptools problems, want to write code that reads the file
formats involved, or want to otherwise tinker with setuptools-generated
files and directories.

Note, however, that these are all internal implementation details and
are therefore subject to change; stick to the published API if you don’t
want to be responsible for keeping your code from breaking when
setuptools changes.  You have been warned.

* Menu:

* Developer’s Guide for Setuptools::
* Release Process::


File: setuptools.info,  Node: Developer’s Guide for Setuptools,  Next: Release Process,  Up: Development on Setuptools

7.1 Developer’s Guide for Setuptools
====================================

If you want to know more about contributing on Setuptools, this is the
place.

* Menu:

* Recommended Reading::
* Project Management::
* Authoring Tickets::
* Making a pull request::
* Auto-Merge Requests::
* Testing::
* Semantic Versioning::
* Building Documentation::
* Vendored Dependencies::


File: setuptools.info,  Node: Recommended Reading,  Next: Project Management,  Up: Developer’s Guide for Setuptools

7.1.1 Recommended Reading
-------------------------

Please read How to write the perfect pull request(1) for some tips on
contributing to open source projects.  Although the article is not
authoritative, it was authored by the maintainer of Setuptools, so
reflects his opinions and will improve the likelihood of acceptance and
quality of contribution.

   ---------- Footnotes ----------

   (1) https://blog.jaraco.com/how-to-write-perfect-pull-request/


File: setuptools.info,  Node: Project Management,  Next: Authoring Tickets,  Prev: Recommended Reading,  Up: Developer’s Guide for Setuptools

7.1.2 Project Management
------------------------

Setuptools is maintained primarily in GitHub at this home(1).
Setuptools is maintained under the Python Packaging Authority (PyPA)
with several core contributors.  All bugs for Setuptools are filed and
the canonical source is maintained in GitHub.

User support and discussions are done through the issue tracker (for
specific) issues, through the distutils-sig mailing list(2), or on IRC
(Freenode) at #pypa.

Discussions about development happen on the distutils-sig mailing list
or on Gitter(3).

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools

   (2) https://mail.python.org/mailman3/lists/distutils-sig.python.org/

   (3) https://gitter.im/pypa/setuptools


File: setuptools.info,  Node: Authoring Tickets,  Next: Making a pull request,  Prev: Project Management,  Up: Developer’s Guide for Setuptools

7.1.3 Authoring Tickets
-----------------------

Before authoring any source code, it’s often prudent to file a ticket
describing the motivation behind making changes.  First search to see if
a ticket already exists for your issue.  If not, create one.  Try to
think from the perspective of the reader.  Explain what behavior you
expected, what you got instead, and what factors might have contributed
to the unexpected behavior.  In GitHub, surround a block of code or
traceback with the triple backtick “‘‘‘” so that it is formatted nicely.

Filing a ticket provides a forum for justification, discussion, and
clarification.  The ticket provides a record of the purpose for the
change and any hard decisions that were made.  It provides a single
place for others to reference when trying to understand why the software
operates the way it does or why certain changes were made.

Setuptools makes extensive use of hyperlinks to tickets in the changelog
so that system integrators and other users can get a quick summary, but
then jump to the in-depth discussion about any subject referenced.


File: setuptools.info,  Node: Making a pull request,  Next: Auto-Merge Requests,  Prev: Authoring Tickets,  Up: Developer’s Guide for Setuptools

7.1.4 Making a pull request
---------------------------

When making a pull request, please *note include a short summary of the
changes: b1. and a reference to any issue tickets that the PR is
intended to solve.  All PRs with code changes should include tests.  All
changes should include a changelog entry.

* Menu:

* Adding change notes with your PRs::
* Alright! So how to add a news fragment?::
* Examples for adding changelog entries to your Pull Requests::


File: setuptools.info,  Node: Adding change notes with your PRs,  Next: Alright! So how to add a news fragment?,  Up: Making a pull request

7.1.4.1 Adding change notes with your PRs
.........................................

It is very important to maintain a log for news of how updating to the
new version of the software will affect end-users.  This is why we
enforce collection of the change fragment files in pull requests as per
Towncrier philosophy(1).

The idea is that when somebody makes a change, they must record the bits
that would affect end-users only including information that would be
useful to them.  Then, when the maintainers publish a new release,
they’ll automatically use these records to compose a change log for the
respective version.  It is important to understand that including
unnecessary low-level implementation related details generates noise
that is not particularly useful to the end-users most of the time.  And
so such details should be recorded in the Git history rather than a
changelog.

   ---------- Footnotes ----------

   (1) 
https://towncrier.readthedocs.io/en/actual-freaking-docs/#philosophy


File: setuptools.info,  Node: Alright! So how to add a news fragment?,  Next: Examples for adding changelog entries to your Pull Requests,  Prev: Adding change notes with your PRs,  Up: Making a pull request

7.1.4.2 Alright! So how to add a news fragment?
...............................................

‘setuptools’ uses towncrier(1) for changelog management.  To submit a
change note about your PR, add a text file into the ‘changelog.d/’
folder.  It should contain an explanation of what applying this PR will
change in the way end-users interact with the project.  One sentence is
usually enough but feel free to add as many details as you feel
necessary for the users to understand what it means.

`Use the past tense' for the text in your fragment because, combined
with others, it will be a part of the “news digest” telling the readers
`what changed' in a specific version of the library `since the previous
version'.  You should also use reStructuredText syntax for highlighting
code (inline or block), linking parts of the docs or external sites.  If
you wish to sign your change, feel free to add ‘-- by
:user:`github-username`’ at the end (replace ‘github-username’ with your
own!).

Finally, name your file following the convention that Towncrier
understands: it should start with the number of an issue or a PR
followed by a dot, then add a patch type, like ‘change’, ‘doc’, ‘misc’
etc., and add ‘.rst’ as a suffix.  If you need to add more than one
fragment, you may add an optional sequence number (delimited with
another period) between the type and the suffix.

In general the name will follow ‘<pr_number>.<category>.rst’ pattern,
where the categories are:

   - ‘change’: Any backwards compatible code change

   - ‘breaking’: Any backwards-compatibility breaking change

   - ‘doc’: A change to the documentation

   - ‘misc’: Changes internal to the repo like CI, test and build
     changes

   - ‘deprecation’: For deprecations of an existing feature or behavior

A pull request may have more than one of these components, for example a
code change may introduce a new feature that deprecates an old feature,
in which case two fragments should be added.  It is not necessary to
make a separate documentation fragment for documentation changes
accompanying the relevant code changes.

   ---------- Footnotes ----------

   (1) https://pypi.org/project/towncrier/


File: setuptools.info,  Node: Examples for adding changelog entries to your Pull Requests,  Prev: Alright! So how to add a news fragment?,  Up: Making a pull request

7.1.4.3 Examples for adding changelog entries to your Pull Requests
...................................................................

File ‘changelog.d/2395.doc.1.rst’:

     Added a ``:user:`` role to Sphinx config -- by :user:`webknjaz`

File ‘changelog.d/1354.misc.rst’:

     Added ``towncrier`` for changelog managment -- by :user:`pganssle`

File ‘changelog.d/2355.change.rst’:

     When pip is imported as part of a build, leave :py:mod:`distutils`
     patched -- by :user:`jaraco`

     Tip: See ‘pyproject.toml’ for all available categories
     (‘tool.towncrier.type’).


File: setuptools.info,  Node: Auto-Merge Requests,  Next: Testing,  Prev: Making a pull request,  Up: Developer’s Guide for Setuptools

7.1.5 Auto-Merge Requests
-------------------------

To support running all code through CI, even lightweight contributions,
the project employs Mergify to auto-merge pull requests tagged as
auto-merge.

Use ‘hub pull-request -l auto-merge’ to create such a pull request from
the command line after pushing a new branch.


File: setuptools.info,  Node: Testing,  Next: Semantic Versioning,  Prev: Auto-Merge Requests,  Up: Developer’s Guide for Setuptools

7.1.6 Testing
-------------

The primary tests are run using tox.  Make sure you have tox installed,
and invoke it:

     $ tox

Under continuous integration, additional tests may be run.  See the
‘.travis.yml’ file for full details on the tests run under Travis-CI.


File: setuptools.info,  Node: Semantic Versioning,  Next: Building Documentation,  Prev: Testing,  Up: Developer’s Guide for Setuptools

7.1.7 Semantic Versioning
-------------------------

Setuptools follows ‘semver’.


File: setuptools.info,  Node: Building Documentation,  Next: Vendored Dependencies,  Prev: Semantic Versioning,  Up: Developer’s Guide for Setuptools

7.1.8 Building Documentation
----------------------------

Setuptools relies on the Sphinx(1) system for building documentation.
The published documentation(2) is hosted on Read the Docs.

To build the docs locally, use tox:

     $ tox -e docs

   ---------- Footnotes ----------

   (1) http://www.sphinx-doc.org/en/master/

   (2) https://setuptools.readthedocs.io/en/latest/


File: setuptools.info,  Node: Vendored Dependencies,  Prev: Building Documentation,  Up: Developer’s Guide for Setuptools

7.1.9 Vendored Dependencies
---------------------------

Setuptools has some dependencies, but due to bootstrapping issues(1),
those dependencies cannot be declared as they won’t be resolved soon
enough to build setuptools from source.  Eventually, this limitation may
be lifted as PEP 517/518 reach ubiquitous adoption, but for now,
Setuptools cannot declare dependencies other than through
‘setuptools/_vendor/vendored.txt’ and
‘pkg_resources/_vendor/vendored.txt’ and refreshed by way of ‘paver
update_vendored’ (pavement.py).

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/980


File: setuptools.info,  Node: Release Process,  Prev: Developer’s Guide for Setuptools,  Up: Development on Setuptools

7.2 Release Process
===================

In order to allow for rapid, predictable releases, Setuptools uses a
mechanical technique for releases, enacted on tagged commits by
continuous integration.

To finalize a release, run ‘tox -e finalize’, review, then push the
changes.

If tests pass, the release will be uploaded to PyPI.

* Menu:

* Release Frequency::
* Release Managers::


File: setuptools.info,  Node: Release Frequency,  Next: Release Managers,  Up: Release Process

7.2.1 Release Frequency
-----------------------

Some have asked why Setuptools is released so frequently.  Because
Setuptools uses a mechanical release process, it’s very easy to make
releases whenever the code is stable (tests are passing).  As a result,
the philosophy is to release early and often.

While some find the frequent releases somewhat surprising, they only
empower the user.  Although releases are made frequently, users can
choose the frequency at which they use those releases.  If instead
Setuptools contributions were only released in batches, the user would
be constrained to only use Setuptools when those official releases were
made.  With frequent releases, the user can govern exactly how often he
wishes to update.

Frequent releases also then obviate the need for dev or beta releases in
most cases.  Because releases are made early and often, bugs are
discovered and corrected quickly, in many cases before other users have
yet to encounter them.


File: setuptools.info,  Node: Release Managers,  Prev: Release Frequency,  Up: Release Process

7.2.2 Release Managers
----------------------

Additionally, anyone with push access to the master branch has access to
cut releases.


File: setuptools.info,  Node: Guides on backward compatibility & deprecated practice,  Next: History<2>,  Prev: Development on Setuptools,  Up: Top

8 Guides on backward compatibility & deprecated practice
********************************************************

‘Setuptools’ has undergone tremendous changes since its first debut.  As
its development continues to roll forward, many of the practice and
mechanisms it had established are now considered deprecated.  But they
still remain relevant as a plethora of libraries continue to depend on
them.  Many people also find it necessary to equip themselves with the
knowledge to better support backward compatibility.  This guide aims to
provide the essential information for such objectives.

* Menu:

* Supporting both Python 2 and Python 3 with Setuptools::
* The Internal Structure of Python Eggs::
* Easy Install::
* Porting from Distutils::
* “Eggsecutable” Scripts::


File: setuptools.info,  Node: Supporting both Python 2 and Python 3 with Setuptools,  Next: The Internal Structure of Python Eggs,  Up: Guides on backward compatibility & deprecated practice

8.1 Supporting both Python 2 and Python 3 with Setuptools
=========================================================

Starting with Distribute version 0.6.2 and Setuptools 0.7, the
Setuptools project supported Python 3.  Installing and using setuptools
for Python 3 code works exactly the same as for Python 2 code.

Setuptools provides a facility to invoke 2to3 on the code as a part of
the build process, by setting the keyword parameter ‘use_2to3’ to True,
but the Setuptools project strongly recommends instead developing a
unified codebase using six(1), future(2), or another compatibility
library.

* Menu:

* Using 2to3::
* Distributing Python 3 modules::
* Advanced features::

   ---------- Footnotes ----------

   (1) https://pypi.org/project/six/

   (2) https://pypi.org/project/future/


File: setuptools.info,  Node: Using 2to3,  Next: Distributing Python 3 modules,  Up: Supporting both Python 2 and Python 3 with Setuptools

8.1.1 Using 2to3
----------------

Setuptools attempts to make the porting process easier by automatically
running 2to3 as a part of running tests.  To do so, you need to
configure the setup.py so that you can run the unit tests with ‘python
setup.py test’.

See *note test - Build package and run a unittest suite: 56. for more
information on this.

Once you have the tests running under Python 2, you can add the use_2to3
keyword parameters to setup(), and start running the tests under Python
3.  The test command will now first run the build command during which
the code will be converted with 2to3, and the tests will then be run
from the build directory, as opposed from the source directory as is
normally done.

Setuptools will convert all Python files, and also all doctests in
Python files.  However, if you have doctests located in separate text
files, these will not automatically be converted.  By adding them to the
‘convert_2to3_doctests’ keyword parameter Setuptools will convert them
as well.

By default, the conversion uses all fixers in the ‘lib2to3.fixers’
package.  To use additional fixers, the parameter ‘use_2to3_fixers’ can
be set to a list of names of packages containing fixers.  To exclude
fixers, the parameter ‘use_2to3_exclude_fixers’ can be set to fixer
names to be skipped.

An example setup.py might look something like this:

     from setuptools import setup

     setup(
         name='your.module',
         version='1.0',
         description='This is your awesome module',
         author='You',
         author_email='your@email',
         package_dir={'': 'src'},
         packages=['your', 'you.module'],
         test_suite='your.module.tests',
         use_2to3=True,
         convert_2to3_doctests=['src/your/module/README.txt'],
         use_2to3_fixers=['your.fixers'],
         use_2to3_exclude_fixers=['lib2to3.fixes.fix_import'],
     )

* Menu:

* Differential conversion::


File: setuptools.info,  Node: Differential conversion,  Up: Using 2to3

8.1.1.1 Differential conversion
...............................

Note that a file will only be copied and converted during the build
process if the source file has been changed.  If you add a file to the
doctests that should be converted, it will not be converted the next
time you run the tests, since it hasn’t been modified.  You need to
remove it from the build directory.  Also if you run the build, install
or test commands before adding the use_2to3 parameter, you will have to
remove the build directory before you run the test command, as the files
otherwise will seem updated, and no conversion will happen.

In general, if code doesn’t seem to be converted, deleting the build
directory and trying again is a good safeguard against the build
directory getting “out of sync” with the source directory.


File: setuptools.info,  Node: Distributing Python 3 modules,  Next: Advanced features,  Prev: Using 2to3,  Up: Supporting both Python 2 and Python 3 with Setuptools

8.1.2 Distributing Python 3 modules
-----------------------------------

You can distribute your modules with Python 3 support in different ways.
A normal source distribution will work, but can be slow in installing,
as the 2to3 process will be run during the install.  But you can also
distribute the module in binary format, such as a binary egg.  That egg
will contain the already converted code, and hence no 2to3 conversion is
needed during install.


File: setuptools.info,  Node: Advanced features,  Prev: Distributing Python 3 modules,  Up: Supporting both Python 2 and Python 3 with Setuptools

8.1.3 Advanced features
-----------------------

If you don’t want to run the 2to3 conversion on the doctests in Python
files, you can turn that off by setting ‘setuptools.use_2to3_on_doctests
= False’.


File: setuptools.info,  Node: The Internal Structure of Python Eggs,  Next: Easy Install,  Prev: Supporting both Python 2 and Python 3 with Setuptools,  Up: Guides on backward compatibility & deprecated practice

8.2 The Internal Structure of Python Eggs
=========================================

STOP! This is not the first document you should read!

* Menu:

* Eggs and their Formats::
* Standard Metadata::
* Other Technical Considerations::


File: setuptools.info,  Node: Eggs and their Formats,  Next: Standard Metadata,  Up: The Internal Structure of Python Eggs

8.2.1 Eggs and their Formats
----------------------------

A “Python egg” is a logical structure embodying the release of a
specific version of a Python project, comprising its code, resources,
and metadata.  There are multiple formats that can be used to physically
encode a Python egg, and others can be developed.  However, a key
principle of Python eggs is that they should be discoverable and
importable.  That is, it should be possible for a Python application to
easily and efficiently find out what eggs are present on a system, and
to ensure that the desired eggs’ contents are importable.

There are two basic formats currently implemented for Python eggs:

  1. ‘.egg’ format: a directory or zipfile `containing' the project’s
     code and resources, along with an ‘EGG-INFO’ subdirectory that
     contains the project’s metadata

  2. ‘.egg-info’ format: a file or directory placed `adjacent' to the
     project’s code and resources, that directly contains the project’s
     metadata.

Both formats can include arbitrary Python code and resources, including
static data files, package and non-package directories, Python modules,
C extension modules, and so on.  But each format is optimized for
different purposes.

The ‘.egg’ format is well-suited to distribution and the easy
uninstallation or upgrades of code, since the project is essentially
self-contained within a single directory or file, unmingled with any
other projects’ code or resources.  It also makes it possible to have
multiple versions of a project simultaneously installed, such that
individual programs can select the versions they wish to use.

The ‘.egg-info’ format, on the other hand, was created to support
backward-compatibility, performance, and ease of installation for system
packaging tools that expect to install all projects’ code and resources
to a single directory (e.g.  ‘site-packages’).  Placing the metadata in
that same directory simplifies the installation process, since it isn’t
necessary to create ‘.pth’ files or otherwise modify ‘sys.path’ to
include each installed egg.

Its disadvantage, however, is that it provides no support for clean
uninstallation or upgrades, and of course only a single version of a
project can be installed to a given directory.  Thus, support from a
package management tool is required.  (This is why setuptools’ “install”
command refers to this type of egg installation as “single-version,
externally managed”.)  Also, they lack sufficient data to allow them to
be copied from their installation source.  easy_install can “ship” an
application by copying ‘.egg’ files or directories to a target location,
but it cannot do this for ‘.egg-info’ installs, because there is no way
to tell what code and resources belong to a particular egg – there may
be several eggs “scrambled” together in a single installation location,
and the ‘.egg-info’ format does not currently include a way to list the
files that were installed.  (This may change in a future version.)

* Menu:

* Code and Resources::
* Project Metadata::
* Filename-Embedded Metadata::
* Egg Links::


File: setuptools.info,  Node: Code and Resources,  Next: Project Metadata,  Up: Eggs and their Formats

8.2.1.1 Code and Resources
..........................

The layout of the code and resources is dictated by Python’s normal
import layout, relative to the egg’s “base location”.

For the ‘.egg’ format, the base location is the ‘.egg’ itself.  That is,
adding the ‘.egg’ filename or directory name to ‘sys.path’ makes its
contents importable.

For the ‘.egg-info’ format, however, the base location is the directory
that `contains' the ‘.egg-info’, and thus it is the directory that must
be added to ‘sys.path’ to make the egg importable.  (Note that this
means that the “normal” installation of a package to a ‘sys.path’
directory is sufficient to make it an “egg” if it has an ‘.egg-info’
file or directory installed alongside of it.)


File: setuptools.info,  Node: Project Metadata,  Next: Filename-Embedded Metadata,  Prev: Code and Resources,  Up: Eggs and their Formats

8.2.1.2 Project Metadata
........................

If eggs contained only code and resources, there would of course be no
difference between them and any other directory or zip file on
‘sys.path’.  Thus, metadata must also be included, using a metadata file
or directory.

For the ‘.egg’ format, the metadata is placed in an ‘EGG-INFO’
subdirectory, directly within the ‘.egg’ file or directory.  For the
‘.egg-info’ format, metadata is stored directly within the ‘.egg-info’
directory itself.

The minimum project metadata that all eggs must have is a standard
Python ‘PKG-INFO’ file, named ‘PKG-INFO’ and placed within the metadata
directory appropriate to the format.  Because it’s possible for this to
be the only metadata file included, ‘.egg-info’ format eggs are not
required to be a directory; they can just be a ‘.egg-info’ file that
directly contains the ‘PKG-INFO’ metadata.  This eliminates the need to
create a directory just to store one file.  This option is `not'
available for ‘.egg’ formats, since setuptools always includes other
metadata.  (In fact, setuptools itself never generates ‘.egg-info’
files, either; the support for using files was added so that the
requirement could easily be satisfied by other tools, such as
distutils).

In addition to the ‘PKG-INFO’ file, an egg’s metadata directory may also
include files and directories representing various forms of optional
standard metadata (see the section on *note Standard Metadata: cb,
below) or user-defined metadata required by the project.  For example,
some projects may define a metadata format to describe their application
plugins, and metadata in this format would then be included by plugin
creators in their projects’ metadata directories.


File: setuptools.info,  Node: Filename-Embedded Metadata,  Next: Egg Links,  Prev: Project Metadata,  Up: Eggs and their Formats

8.2.1.3 Filename-Embedded Metadata
..................................

To allow introspection of installed projects and runtime resolution of
inter-project dependencies, a certain amount of information is embedded
in egg filenames.  At a minimum, this includes the project name, and
ideally will also include the project version number.  Optionally, it
can also include the target Python version and required runtime platform
if platform-specific C code is included.  The syntax of an egg filename
is as follows:

     name ["-" version ["-py" pyver ["-" required_platform]]] "." ext

The “name” and “version” should be escaped using the ‘to_filename()’
function provided by ‘pkg_resources’, after first processing them with
‘safe_name()’ and ‘safe_version()’ respectively.  These latter two
functions can also be used to later “unescape” these parts of the
filename.  (For a detailed description of these transformations, please
see the “Parsing Utilities” section of the ‘pkg_resources’ manual.)

The “pyver” string is the Python major version, as found in the first 3
characters of ‘sys.version’.  “required_platform” is essentially a
distutils ‘get_platform()’ string, but with enhancements to properly
distinguish Mac OS versions.  (See the ‘get_build_platform()’
documentation in the “Platform Utilities” section of the ‘pkg_resources’
manual for more details.)

Finally, the “ext” is either ‘.egg’ or ‘.egg-info’, as appropriate for
the egg’s format.

Normally, an egg’s filename should include at least the project name and
version, as this allows the runtime system to find desired project
versions without having to read the egg’s PKG-INFO to determine its
version number.

Setuptools, however, only includes the version number in the filename
when an ‘.egg’ file is built using the ‘bdist_egg’ command, or when an
‘.egg-info’ directory is being installed by the ‘install_egg_info’
command.  When generating metadata for use with the original source
tree, it only includes the project name, so that the directory will not
have to be renamed each time the project’s version changes.

This is especially important when version numbers change frequently, and
the source metadata directory is kept under version control with the
rest of the project.  (As would be the case when the project’s source
includes project-defined metadata that is not generated from by
setuptools from data in the setup script.)


File: setuptools.info,  Node: Egg Links,  Prev: Filename-Embedded Metadata,  Up: Eggs and their Formats

8.2.1.4 Egg Links
.................

In addition to the ‘.egg’ and ‘.egg-info’ formats, there is a third
egg-related extension that you may encounter on occasion: ‘.egg-link’
files.

These files are not eggs, strictly speaking.  They simply provide a way
to reference an egg that is not physically installed in the desired
location.  They exist primarily as a cross-platform alternative to
symbolic links, to support “installing” code that is being developed in
a different location than the desired installation location.  For
example, if a user is developing an application plugin in their home
directory, but the plugin needs to be “installed” in an application
plugin directory, running “setup.py develop -md /path/to/app/plugins”
will install an ‘.egg-link’ file in ‘/path/to/app/plugins’, that tells
the egg runtime system where to find the actual egg (the user’s project
source directory and its ‘.egg-info’ subdirectory).

‘.egg-link’ files are named following the format for ‘.egg’ and
‘.egg-info’ names, but only the project name is included; no version,
Python version, or platform information is included.  When the runtime
searches for available eggs, ‘.egg-link’ files are opened and the actual
egg file/directory name is read from them.

Each ‘.egg-link’ file should contain a single file or directory name,
with no newlines.  This filename should be the base location of one or
more eggs.  That is, the name must either end in ‘.egg’, or else it
should be the parent directory of one or more ‘.egg-info’ format eggs.

As of setuptools 0.6c6, the path may be specified as a
platform-independent (i.e.  ‘/’-separated) relative path from the
directory containing the ‘.egg-link’ file, and a second line may appear
in the file, specifying a platform-independent relative path from the
egg’s base directory to its setup script directory.  This allows
installation tools such as EasyInstall to find the project’s setup
directory and build eggs or perform other setup commands on it.


File: setuptools.info,  Node: Standard Metadata,  Next: Other Technical Considerations,  Prev: Eggs and their Formats,  Up: The Internal Structure of Python Eggs

8.2.2 Standard Metadata
-----------------------

In addition to the minimum required ‘PKG-INFO’ metadata, projects can
include a variety of standard metadata files or directories, as
described below.  Except as otherwise noted, these files and directories
are automatically generated by setuptools, based on information supplied
in the setup script or through analysis of the project’s code and
resources.

Most of these files and directories are generated via “egg-info writers”
during execution of the setuptools ‘egg_info’ command, and are listed in
the ‘egg_info.writers’ entry point group defined by setuptools’ own
‘setup.py’ file.

Project authors can register their own metadata writers as entry points
in this group (as described in the setuptools manual under “Adding new
EGG-INFO Files”) to cause setuptools to generate project-specific
metadata files or directories during execution of the ‘egg_info’
command.  It is up to project authors to document these new metadata
formats, if they create any.

* Menu:

* .txt File Formats: txt File Formats.
* Dependency Metadata::
* namespace_packages.txt – Namespace Package Metadata: namespace_packages txt – Namespace Package Metadata.
* entry_points.txt – “Entry Point”/Plugin Metadata: entry_points txt – “Entry Point”/Plugin Metadata.
* The scripts Subdirectory::
* Zip Support Metadata::
* top_level.txt – Conflict Management Metadata: top_level txt – Conflict Management Metadata.
* SOURCES.txt – Source Files Manifest: SOURCES txt – Source Files Manifest.


File: setuptools.info,  Node: txt File Formats,  Next: Dependency Metadata,  Up: Standard Metadata

8.2.2.1 ‘.txt’ File Formats
...........................

Files described in this section that have ‘.txt’ extensions have a
simple lexical format consisting of a sequence of text lines, each line
terminated by a linefeed character (regardless of platform).  Leading
and trailing whitespace on each line is ignored, as are blank lines and
lines whose first nonblank character is a ‘#’ (comment symbol).  (This
is the parsing format defined by the ‘yield_lines()’ function of the
‘pkg_resources’ module.)

All ‘.txt’ files defined by this section follow this format, but some
are also “sectioned” files, meaning that their contents are divided into
sections, using square-bracketed section headers akin to Windows ‘.ini’
format.  Note that this does `not' imply that the lines within the
sections follow an ‘.ini’ format, however.  Please see an individual
metadata file’s documentation for a description of what the lines and
section names mean in that particular file.

Sectioned files can be parsed using the ‘split_sections()’ function; see
the “Parsing Utilities” section of the ‘pkg_resources’ manual for for
details.


File: setuptools.info,  Node: Dependency Metadata,  Next: namespace_packages txt – Namespace Package Metadata,  Prev: txt File Formats,  Up: Standard Metadata

8.2.2.2 Dependency Metadata
...........................

* Menu:

* requires.txt: requires txt.
* setup_requires.txt: setup_requires txt.
* dependency_links.txt: dependency_links txt.
* depends.txt – Obsolete, do not create!: depends txt – Obsolete do not create!.


File: setuptools.info,  Node: requires txt,  Next: setup_requires txt,  Up: Dependency Metadata

8.2.2.3 ‘requires.txt’
......................

This is a “sectioned” text file.  Each section is a sequence of
“requirements”, as parsed by the ‘parse_requirements()’ function; please
see the ‘pkg_resources’ manual for the complete requirement parsing
syntax.

The first, unnamed section (i.e., before the first section header) in
this file is the project’s core requirements, which must be installed
for the project to function.  (Specified using the ‘install_requires’
keyword to ‘setup()’).

The remaining (named) sections describe the project’s “extra”
requirements, as specified using the ‘extras_require’ keyword to
‘setup()’.  The section name is the name of the optional feature, and
the section body lists that feature’s dependencies.

Note that it is not normally necessary to inspect this file directly;
‘pkg_resources.Distribution’ objects have a ‘requires()’ method that can
be used to obtain ‘Requirement’ objects describing the project’s core
and optional dependencies.


File: setuptools.info,  Node: setup_requires txt,  Next: dependency_links txt,  Prev: requires txt,  Up: Dependency Metadata

8.2.2.4 ‘setup_requires.txt’
............................

Much like ‘requires.txt’ except represents the requirements specified by
the ‘setup_requires’ parameter to the Distribution.


File: setuptools.info,  Node: dependency_links txt,  Next: depends txt – Obsolete do not create!,  Prev: setup_requires txt,  Up: Dependency Metadata

8.2.2.5 ‘dependency_links.txt’
..............................

A list of dependency URLs, one per line, as specified using the
‘dependency_links’ keyword to ‘setup()’.  These may be direct download
URLs, or the URLs of web pages containing direct download links.  Please
see the setuptools manual for more information on specifying this
option.


File: setuptools.info,  Node: depends txt – Obsolete do not create!,  Prev: dependency_links txt,  Up: Dependency Metadata

8.2.2.6 ‘depends.txt’ – Obsolete, do not create!
................................................

This file follows an identical format to ‘requires.txt’, but is obsolete
and should not be used.  The earliest versions of setuptools required
users to manually create and maintain this file, so the runtime still
supports reading it, if it exists.  The new filename was created so that
it could be automatically generated from ‘setup()’ information without
overwriting an existing hand-created ‘depends.txt’, if one was already
present in the project’s source ‘.egg-info’ directory.


File: setuptools.info,  Node: namespace_packages txt – Namespace Package Metadata,  Next: entry_points txt – “Entry Point”/Plugin Metadata,  Prev: Dependency Metadata,  Up: Standard Metadata

8.2.2.7 ‘namespace_packages.txt’ – Namespace Package Metadata
.............................................................

A list of namespace package names, one per line, as supplied to the
‘namespace_packages’ keyword to ‘setup()’.  Please see the manuals for
setuptools and ‘pkg_resources’ for more information about namespace
packages.


File: setuptools.info,  Node: entry_points txt – “Entry Point”/Plugin Metadata,  Next: The scripts Subdirectory,  Prev: namespace_packages txt – Namespace Package Metadata,  Up: Standard Metadata

8.2.2.8 ‘entry_points.txt’ – “Entry Point”/Plugin Metadata
..........................................................

This is a “sectioned” text file, whose contents encode the
‘entry_points’ keyword supplied to ‘setup()’.  All sections are named,
as the section names specify the entry point groups in which the
corresponding section’s entry points are registered.

Each section is a sequence of “entry point” lines, each parseable using
the ‘EntryPoint.parse’ classmethod; please see the ‘pkg_resources’
manual for the complete entry point parsing syntax.

Note that it is not necessary to parse this file directly; the
‘pkg_resources’ module provides a variety of APIs to locate and load
entry points automatically.  Please see the setuptools and
‘pkg_resources’ manuals for details on the nature and uses of entry
points.


File: setuptools.info,  Node: The scripts Subdirectory,  Next: Zip Support Metadata,  Prev: entry_points txt – “Entry Point”/Plugin Metadata,  Up: Standard Metadata

8.2.2.9 The ‘scripts’ Subdirectory
..................................

This directory is currently only created for ‘.egg’ files built by the
setuptools ‘bdist_egg’ command.  It will contain copies of all of the
project’s “traditional” scripts (i.e., those specified using the
‘scripts’ keyword to ‘setup()’).  This is so that they can be
reconstituted when an ‘.egg’ file is installed.

The scripts are placed here using the distutils’ standard
‘install_scripts’ command, so any ‘#!’ lines reflect the Python
installation where the egg was built.  But instead of copying the
scripts to the local script installation directory, EasyInstall writes
short wrapper scripts that invoke the original scripts from inside the
egg, after ensuring that sys.path includes the egg and any eggs it
depends on.  For more about *note script wrappers: d7, see the section
below on *note Installation and Path Management Issues: d8.


File: setuptools.info,  Node: Zip Support Metadata,  Next: top_level txt – Conflict Management Metadata,  Prev: The scripts Subdirectory,  Up: Standard Metadata

8.2.2.10 Zip Support Metadata
.............................

* Menu:

* native_libs.txt: native_libs txt.
* eager_resources.txt: eager_resources txt.
* zip-safe and not-zip-safe::


File: setuptools.info,  Node: native_libs txt,  Next: eager_resources txt,  Up: Zip Support Metadata

8.2.2.11 ‘native_libs.txt’
..........................

A list of C extensions and other dynamic link libraries contained in the
egg, one per line.  Paths are ‘/’-separated and relative to the egg’s
base location.

This file is generated as part of ‘bdist_egg’ processing, and as such
only appears in ‘.egg’ files (and ‘.egg’ directories created by
unpacking them).  It is used to ensure that all libraries are extracted
from a zipped egg at the same time, in case there is any direct linkage
between them.  Please see the *note Zip File Issues: db. section below
for more information on library and resource extraction from ‘.egg’
files.


File: setuptools.info,  Node: eager_resources txt,  Next: zip-safe and not-zip-safe,  Prev: native_libs txt,  Up: Zip Support Metadata

8.2.2.12 ‘eager_resources.txt’
..............................

A list of resource files and/or directories, one per line, as specified
via the ‘eager_resources’ keyword to ‘setup()’.  Paths are ‘/’-separated
and relative to the egg’s base location.

Resource files or directories listed here will be extracted
simultaneously, if any of the named resources are extracted, or if any
native libraries listed in ‘native_libs.txt’ are extracted.  Please see
the setuptools manual for details on what this feature is used for and
how it works, as well as the *note Zip File Issues: db. section below.


File: setuptools.info,  Node: zip-safe and not-zip-safe,  Prev: eager_resources txt,  Up: Zip Support Metadata

8.2.2.13 ‘zip-safe’ and ‘not-zip-safe’
......................................

These are zero-length files, and either one or the other should exist.
If ‘zip-safe’ exists, it means that the project will work properly when
installed as an ‘.egg’ zipfile, and conversely the existence of
‘not-zip-safe’ means the project should not be installed as an ‘.egg’
file.  The ‘zip_safe’ option to setuptools’ ‘setup()’ determines which
file will be written.  If the option isn’t provided, setuptools attempts
to make its own assessment of whether the package can work, based on
code and content analysis.

If neither file is present at installation time, EasyInstall defaults to
assuming that the project should be unzipped.  (Command-line options to
EasyInstall, however, take precedence even over an existing ‘zip-safe’
or ‘not-zip-safe’ file.)

Note that these flag files appear only in ‘.egg’ files generated by
‘bdist_egg’, and in ‘.egg’ directories created by unpacking such an
‘.egg’ file.


File: setuptools.info,  Node: top_level txt – Conflict Management Metadata,  Next: SOURCES txt – Source Files Manifest,  Prev: Zip Support Metadata,  Up: Standard Metadata

8.2.2.14 ‘top_level.txt’ – Conflict Management Metadata
.......................................................

This file is a list of the top-level module or package names provided by
the project, one Python identifier per line.

Subpackages are not included; a project containing both a ‘foo.bar’ and
a ‘foo.baz’ would include only one line, ‘foo’, in its ‘top_level.txt’.

This data is used by ‘pkg_resources’ at runtime to issue a warning if an
egg is added to ‘sys.path’ when its contained packages may have already
been imported.

(It was also once used to detect conflicts with non-egg packages at
installation time, but in more recent versions, setuptools installs eggs
in such a way that they always override non-egg packages, thus
preventing a problem from arising.)


File: setuptools.info,  Node: SOURCES txt – Source Files Manifest,  Prev: top_level txt – Conflict Management Metadata,  Up: Standard Metadata

8.2.2.15 ‘SOURCES.txt’ – Source Files Manifest
..............................................

This file is roughly equivalent to the distutils’ ‘MANIFEST’ file.  The
differences are as follows:

   * The filenames always use ‘/’ as a path separator, which must be
     converted back to a platform-specific path whenever they are read.

   * The file is automatically generated by setuptools whenever the
     ‘egg_info’ or ‘sdist’ commands are run, and it is `not'
     user-editable.

Although this metadata is included with distributed eggs, it is not
actually used at runtime for any purpose.  Its function is to ensure
that setuptools-built `source' distributions can correctly discover what
files are part of the project’s source, even if the list had been
generated using revision control metadata on the original author’s
system.

In other words, ‘SOURCES.txt’ has little or no runtime value for being
included in distributed eggs, and it is possible that future versions of
the ‘bdist_egg’ and ‘install_egg_info’ commands will strip it before
installation or distribution.  Therefore, do not rely on its being
available outside of an original source directory or source
distribution.


File: setuptools.info,  Node: Other Technical Considerations,  Prev: Standard Metadata,  Up: The Internal Structure of Python Eggs

8.2.3 Other Technical Considerations
------------------------------------

* Menu:

* Zip File Issues::
* Installation and Path Management Issues::


File: setuptools.info,  Node: Zip File Issues,  Next: Installation and Path Management Issues,  Up: Other Technical Considerations

8.2.3.1 Zip File Issues
.......................

Although zip files resemble directories, they are not fully
substitutable for them.  Most platforms do not support loading dynamic
link libraries contained in zipfiles, so it is not possible to directly
import C extensions from ‘.egg’ zipfiles.  Similarly, there are many
existing libraries – whether in Python or C – that require actual
operating system filenames, and do not work with arbitrary “file-like”
objects or in-memory strings, and thus cannot operate directly on the
contents of zip files.

To address these issues, the ‘pkg_resources’ module provides a “resource
API” to support obtaining either the contents of a resource, or a true
operating system filename for the resource.  If the egg containing the
resource is a directory, the resource’s real filename is simply
returned.  However, if the egg is a zipfile, then the resource is first
extracted to a cache directory, and the filename within the cache is
returned.

The cache directory is determined by the ‘pkg_resources’ API; please see
the ‘set_cache_path()’ and ‘get_default_cache()’ documentation for
details.

* Menu:

* The Extraction Process::
* Extension Import Wrappers::


File: setuptools.info,  Node: The Extraction Process,  Next: Extension Import Wrappers,  Up: Zip File Issues

8.2.3.2 The Extraction Process
..............................

Resources are extracted to a cache subdirectory whose name is based on
the enclosing ‘.egg’ filename and the path to the resource.  If there is
already a file of the correct name, size, and timestamp, its filename is
returned to the requester.  Otherwise, the desired file is extracted
first to a temporary name generated using
‘mkstemp(".$extract",target_dir)’, and then its timestamp is set to
match the one in the zip file, before renaming it to its final name.
(Some collision detection and resolution code is used to handle the fact
that Windows doesn’t overwrite files when renaming.)

If a resource directory is requested, all of its contents are
recursively extracted in this fashion, to ensure that the directory name
can be used as if it were valid all along.

If the resource requested for extraction is listed in the
‘native_libs.txt’ or ‘eager_resources.txt’ metadata files, then `all'
resources listed in `either' file will be extracted before the requested
resource’s filename is returned, thus ensuring that all C extensions and
data used by them will be simultaneously available.


File: setuptools.info,  Node: Extension Import Wrappers,  Prev: The Extraction Process,  Up: Zip File Issues

8.2.3.3 Extension Import Wrappers
.................................

Since Python’s built-in zip import feature does not support loading C
extension modules from zipfiles, the setuptools ‘bdist_egg’ command
generates special import wrappers to make it work.

The wrappers are ‘.py’ files (along with corresponding ‘.pyc’ and/or
‘.pyo’ files) that have the same module name as the corresponding C
extension.  These wrappers are located in the same package directory (or
top-level directory) within the zipfile, so that say, ‘foomodule.so’
will get a corresponding ‘foo.py’, while ‘bar/baz.pyd’ will get a
corresponding ‘bar/baz.py’.

These wrapper files contain a short stanza of Python code that asks
‘pkg_resources’ for the filename of the corresponding C extension, then
reloads the module using the obtained filename.  This will cause
‘pkg_resources’ to first ensure that all of the egg’s C extensions (and
any accompanying “eager resources”) are extracted to the cache before
attempting to link to the C library.

Note, by the way, that ‘.egg’ directories will also contain these
wrapper files.  However, Python’s default import priority is such that C
extensions take precedence over same-named Python modules, so the import
wrappers are ignored unless the egg is a zipfile.


File: setuptools.info,  Node: Installation and Path Management Issues,  Prev: Zip File Issues,  Up: Other Technical Considerations

8.2.3.4 Installation and Path Management Issues
...............................................

Python’s initial setup of ‘sys.path’ is very dependent on the Python
version and installation platform, as well as how Python was started
(i.e., script vs.  ‘-c’ vs.  ‘-m’ vs.  interactive interpreter).  In
fact, Python also provides only two relatively robust ways to affect
‘sys.path’ outside of direct manipulation in code: the ‘PYTHONPATH’
environment variable, and ‘.pth’ files.

However, with no cross-platform way to safely and persistently change
environment variables, this leaves ‘.pth’ files as EasyInstall’s only
real option for persistent configuration of ‘sys.path’.

But ‘.pth’ files are rather strictly limited in what they are allowed to
do normally.  They add directories only to the `end' of ‘sys.path’,
after any locally-installed ‘site-packages’ directory, and they are only
processed `in' the ‘site-packages’ directory to start with.

This is a double whammy for users who lack write access to that
directory, because they can’t create a ‘.pth’ file that Python will
read, and even if a sympathetic system administrator adds one for them
that calls ‘site.addsitedir()’ to allow some other directory to contain
‘.pth’ files, they won’t be able to install newer versions of anything
that’s installed in the systemwide ‘site-packages’, because their paths
will still be added `after' ‘site-packages’.

So EasyInstall applies two workarounds to solve these problems.

The first is that EasyInstall leverages ‘.pth’ files’ “import” feature
to manipulate ‘sys.path’ and ensure that anything EasyInstall adds to a
‘.pth’ file will always appear before both the standard library and the
local ‘site-packages’ directories.  Thus, it is always possible for a
user who can write a Python-read ‘.pth’ file to ensure that their
packages come first in their own environment.

Second, when installing to a ‘PYTHONPATH’ directory (as opposed to a
“site” directory like ‘site-packages’) EasyInstall will also install a
special version of the ‘site’ module.  Because it’s in a ‘PYTHONPATH’
directory, this module will get control before the standard library
version of ‘site’ does.  It will record the state of ‘sys.path’ before
invoking the “real” ‘site’ module, and then afterwards it processes any
‘.pth’ files found in ‘PYTHONPATH’ directories, including all the fixups
needed to ensure that eggs always appear before the standard library in
sys.path, but are in a relative order to one another that is defined by
their ‘PYTHONPATH’ and ‘.pth’-prescribed sequence.

The net result of these changes is that ‘sys.path’ order will be as
follows at runtime:

  1. The ‘sys.argv[0]’ directory, or an empty string if no script is
     being executed.

  2. All eggs installed by EasyInstall in any ‘.pth’ file in each
     ‘PYTHONPATH’ directory, in order first by ‘PYTHONPATH’ order, then
     normal ‘.pth’ processing order (which is to say alphabetical by
     ‘.pth’ filename, then by the order of listing within each ‘.pth’
     file).

  3. All eggs installed by EasyInstall in any ‘.pth’ file in each “site”
     directory (such as ‘site-packages’), following the same ordering
     rules as for the ones on ‘PYTHONPATH’.

  4. The ‘PYTHONPATH’ directories themselves, in their original order

  5. Any paths from ‘.pth’ files found on ‘PYTHONPATH’ that were `not'
     eggs installed by EasyInstall, again following the same relative
     ordering rules.

  6. The standard library and “site” directories, along with the
     contents of any ‘.pth’ files found in the “site” directories.

Notice that sections 1, 4, and 6 comprise the “normal” Python setup for
‘sys.path’.  Sections 2 and 3 are inserted to support eggs, and section
5 emulates what the “normal” semantics of ‘.pth’ files on ‘PYTHONPATH’
would be if Python natively supported them.

For further discussion of the tradeoffs that went into this design, as
well as notes on the actual magic inserted into ‘.pth’ files to make
them do these things, please see also the following messages to the
distutils-SIG mailing list:

   * 
     ‘http://mail.python.org/pipermail/distutils-sig/2006-February/006026.html’

   * 
     ‘http://mail.python.org/pipermail/distutils-sig/2006-March/006123.html’

* Menu:

* Script Wrappers::


File: setuptools.info,  Node: Script Wrappers,  Up: Installation and Path Management Issues

8.2.3.5 Script Wrappers
.......................

EasyInstall never directly installs a project’s original scripts to a
script installation directory.  Instead, it writes short wrapper scripts
that first ensure that the project’s dependencies are active on
sys.path, before invoking the original script.  These wrappers have a #!
line that points to the version of Python that was used to install them,
and their second line is always a comment that indicates the type of
script wrapper, the project version required for the script to run, and
information identifying the script to be invoked.

The format of this marker line is:

     "# EASY-INSTALL-" script_type ": " tuple_of_strings "\n"

The ‘script_type’ is one of ‘SCRIPT’, ‘DEV-SCRIPT’, or ‘ENTRY-SCRIPT’.
The ‘tuple_of_strings’ is a comma-separated sequence of Python string
constants.  For ‘SCRIPT’ and ‘DEV-SCRIPT’ wrappers, there are two
strings: the project version requirement, and the script name (as a
filename within the ‘scripts’ metadata directory).  For ‘ENTRY-SCRIPT’
wrappers, there are three: the project version requirement, the entry
point group name, and the entry point name.  (See the “Automatic Script
Creation” section in the setuptools manual for more information about
entry point scripts.)

In each case, the project version requirement string will be a string
parseable with the ‘pkg_resources’ modules’ ‘Requirement.parse()’
classmethod.  The only difference between a ‘SCRIPT’ wrapper and a
‘DEV-SCRIPT’ is that a ‘DEV-SCRIPT’ actually executes the original
source script in the project’s source tree, and is created when the
“setup.py develop” command is run.  A ‘SCRIPT’ wrapper, on the other
hand, uses the “installed” script written to the ‘EGG-INFO/scripts’
subdirectory of the corresponding ‘.egg’ zipfile or directory.
(‘.egg-info’ eggs do not have script wrappers associated with them,
except in the “setup.py develop” case.)

The purpose of including the marker line in generated script wrappers is
to facilitate introspection of installed scripts, and their relationship
to installed eggs.  For example, an uninstallation tool could use this
data to identify what scripts can safely be removed, and/or identify
what scripts would stop working if a particular egg is uninstalled.


File: setuptools.info,  Node: Easy Install,  Next: Porting from Distutils,  Prev: The Internal Structure of Python Eggs,  Up: Guides on backward compatibility & deprecated practice

8.3 Easy Install
================

     Warning: Easy Install is deprecated.  Do not use it.  Instead use
     pip.  If you think you need Easy Install, please reach out to the
     PyPA team (a ticket to pip or setuptools is fine), describing your
     use-case.

Easy Install is a python module (‘easy_install’) bundled with
‘setuptools’ that lets you automatically download, build, install, and
manage Python packages.

Please share your experiences with us!  If you encounter difficulty
installing a package, please contact us via the distutils mailing
list(1).  (Note: please DO NOT send private email directly to the author
of setuptools; it will be discarded.  The mailing list is a searchable
archive of previously-asked and answered questions; you should begin
your research there before reporting something as a bug – and then do so
via list discussion first.)

(Also, if you’d like to learn about how you can use ‘setuptools’ to make
your own packages work better with EasyInstall, or provide
EasyInstall-like features without requiring your users to use
EasyInstall directly, you’ll probably want to check out the full
documentation as well.)

* Menu:

* Using “Easy Install”::
* Reference Manual::

   ---------- Footnotes ----------

   (1) http://mail.python.org/pipermail/distutils-sig/


File: setuptools.info,  Node: Using “Easy Install”,  Next: Reference Manual,  Up: Easy Install

8.3.1 Using “Easy Install”
--------------------------

* Menu:

* Installing “Easy Install”::
* Downloading and Installing a Package::
* Upgrading a Package::
* Changing the Active Version::
* Uninstalling Packages::
* Managing Scripts::
* Executables and Launchers::
* Tips & Techniques::
* Password-Protected Sites::
* Using .pypirc Credentials: Using pypirc Credentials.


File: setuptools.info,  Node: Installing “Easy Install”,  Next: Downloading and Installing a Package,  Up: Using “Easy Install”

8.3.1.1 Installing “Easy Install”
.................................

Please see the setuptools PyPI page(1) for download links and basic
installation instructions for each of the supported platforms.

You will need at least Python 3.5 or 2.7.  An ‘easy_install’ script will
be installed in the normal location for Python scripts on your platform.

Note that the instructions on the setuptools PyPI page assume that you
are are installing to Python’s primary ‘site-packages’ directory.  If
this is not the case, you should consult the section below on *note
Custom Installation Locations: e8. before installing.  (And, on Windows,
you should not use the ‘.exe’ installer when installing to an alternate
location.)

Note that ‘easy_install’ normally works by downloading files from the
internet.  If you are behind an NTLM-based firewall that prevents Python
programs from accessing the net directly, you may wish to first install
and use the APS proxy server(2), which lets you get past such firewalls
in the same way that your web browser(s) do.

(Alternately, if you do not wish easy_install to actually download
anything, you can restrict it from doing so with the ‘--allow-hosts’
option; see the sections on *note restricting downloads with
–allow-hosts: e9. and *note command-line options: ea. for more details.)

* Menu:

* Troubleshooting::
* Windows Notes::

   ---------- Footnotes ----------

   (1) https://pypi.org/project/setuptools/

   (2) http://ntlmaps.sf.net/


File: setuptools.info,  Node: Troubleshooting,  Next: Windows Notes,  Up: Installing “Easy Install”

8.3.1.2 Troubleshooting
.......................

If EasyInstall/setuptools appears to install correctly, and you can run
the ‘easy_install’ command but it fails with an ‘ImportError’, the most
likely cause is that you installed to a location other than
‘site-packages’, without taking any of the steps described in the *note
Custom Installation Locations: e8. section below.  Please see that
section and follow the steps to make sure that your custom location will
work correctly.  Then re-install.

Similarly, if you can run ‘easy_install’, and it appears to be
installing packages, but then you can’t import them, the most likely
issue is that you installed EasyInstall correctly but are using it to
install packages to a non-standard location that hasn’t been properly
prepared.  Again, see the section on *note Custom Installation
Locations: e8. for more details.


File: setuptools.info,  Node: Windows Notes,  Prev: Troubleshooting,  Up: Installing “Easy Install”

8.3.1.3 Windows Notes
.....................

Installing setuptools will provide an ‘easy_install’ command according
to the techniques described in *note Executables and Launchers: ed.  If
the ‘easy_install’ command is not available after installation, that
section provides details on how to configure Windows to make the
commands available.


File: setuptools.info,  Node: Downloading and Installing a Package,  Next: Upgrading a Package,  Prev: Installing “Easy Install”,  Up: Using “Easy Install”

8.3.1.4 Downloading and Installing a Package
............................................

For basic use of ‘easy_install’, you need only supply the filename or
URL of a source distribution or .egg file (Python Egg(1)).

`Example 1'.  Install a package by name, searching PyPI for the latest
version, and automatically downloading, building, and installing it:

     easy_install SQLObject

`Example 2'.  Install or upgrade a package by name and version by
finding links on a given “download page”:

     easy_install -f http://pythonpaste.org/package_index.html SQLObject

`Example 3'.  Download a source distribution from a specified URL,
automatically building and installing it:

     easy_install http://example.com/path/to/MyPackage-1.2.3.tgz

`Example 4'.  Install an already-downloaded .egg file:

     easy_install /my_downloads/OtherPackage-3.2.1-py2.3.egg

`Example 5'.  Upgrade an already-installed package to the latest version
listed on PyPI:

     easy_install --upgrade PyProtocols

`Example 6'.  Install a source distribution that’s already downloaded
and extracted in the current directory (New in 0.5a9):

     easy_install .

`Example 7'.  (New in 0.6a1) Find a source distribution or Subversion
checkout URL for a package, and extract it or check it out to
‘~/projects/sqlobject’ (the name will always be in all-lowercase), where
it can be examined or edited.  (The package will not be installed, but
it can easily be installed with ‘easy_install ~/projects/sqlobject’.
See *note Editing and Viewing Source Packages: ef. below for more
info.):

     easy_install --editable --build-directory ~/projects SQLObject

`Example 7'.  (New in 0.6.11) Install a distribution within your home
dir:

     easy_install --user SQLAlchemy

Easy Install accepts URLs, filenames, PyPI package names (i.e.,
‘distutils’ “distribution” names), and package+version specifiers.  In
each case, it will attempt to locate the latest available version that
meets your criteria.

When downloading or processing downloaded files, Easy Install recognizes
distutils source distribution files with extensions of .tgz, .tar,
.tar.gz, .tar.bz2, or .zip.  And of course it handles already-built .egg
distributions as well as ‘.win32.exe’ installers built using distutils.

By default, packages are installed to the running Python installation’s
‘site-packages’ directory, unless you provide the ‘-d’ or
‘--install-dir’ option to specify an alternative directory, or specify
an alternate location using distutils configuration files.  (See *note
Configuration Files: f0, below.)

By default, any scripts included with the package are installed to the
running Python installation’s standard script installation location.
However, if you specify an installation directory via the command line
or a config file, then the default directory for installing scripts will
be the same as the package installation directory, to ensure that the
script will have access to the installed package.  You can override this
using the ‘-s’ or ‘--script-dir’ option.

Installed packages are added to an ‘easy-install.pth’ file in the
install directory, so that Python will always use the
most-recently-installed version of the package.  If you would like to be
able to select which version to use at runtime, you should use the ‘-m’
or ‘--multi-version’ option.

   ---------- Footnotes ----------

   (1) http://peak.telecommunity.com/DevCenter/PythonEggs


File: setuptools.info,  Node: Upgrading a Package,  Next: Changing the Active Version,  Prev: Downloading and Installing a Package,  Up: Using “Easy Install”

8.3.1.5 Upgrading a Package
...........................

You don’t need to do anything special to upgrade a package: just install
the new version, either by requesting a specific version, e.g.:

     easy_install "SomePackage==2.0"

a version greater than the one you have now:

     easy_install "SomePackage>2.0"

using the upgrade flag, to find the latest available version on PyPI:

     easy_install --upgrade SomePackage

or by using a download page, direct download URL, or package filename:

     easy_install -f http://example.com/downloads ExamplePackage

     easy_install http://example.com/downloads/ExamplePackage-2.0-py2.4.egg

     easy_install my_downloads/ExamplePackage-2.0.tgz

If you’re using ‘-m’ or ‘--multi-version’ , using the ‘require()’
function at runtime automatically selects the newest installed version
of a package that meets your version criteria.  So, installing a newer
version is the only step needed to upgrade such packages.

If you’re installing to a directory on PYTHONPATH, or a configured
“site” directory (and not using ‘-m’), installing a package
automatically replaces any previous version in the ‘easy-install.pth’
file, so that Python will import the most-recently installed version by
default.  So, again, installing the newer version is the only upgrade
step needed.

If you haven’t suppressed script installation (using ‘--exclude-scripts’
or ‘-x’), then the upgraded version’s scripts will be installed, and
they will be automatically patched to ‘require()’ the corresponding
version of the package, so that you can use them even if they are
installed in multi-version mode.

‘easy_install’ never actually deletes packages (unless you’re installing
a package with the same name and version number as an existing package),
so if you want to get rid of older versions of a package, please see
*note Uninstalling Packages: f2, below.


File: setuptools.info,  Node: Changing the Active Version,  Next: Uninstalling Packages,  Prev: Upgrading a Package,  Up: Using “Easy Install”

8.3.1.6 Changing the Active Version
...................................

If you’ve upgraded a package, but need to revert to a
previously-installed version, you can do so like this:

     easy_install PackageName==1.2.3

Where ‘1.2.3’ is replaced by the exact version number you wish to switch
to.  If a package matching the requested name and version is not already
installed in a directory on ‘sys.path’, it will be located via PyPI and
installed.

If you’d like to switch to the latest installed version of
‘PackageName’, you can do so like this:

     easy_install PackageName

This will activate the latest installed version.  (Note: if you have set
any ‘find_links’ via distutils configuration files, those download pages
will be checked for the latest available version of the package, and it
will be downloaded and installed if it is newer than your current
version.)

Note that changing the active version of a package will install the
newly active version’s scripts, unless the ‘--exclude-scripts’ or ‘-x’
option is specified.


File: setuptools.info,  Node: Uninstalling Packages,  Next: Managing Scripts,  Prev: Changing the Active Version,  Up: Using “Easy Install”

8.3.1.7 Uninstalling Packages
.............................

If you have replaced a package with another version, then you can just
delete the package(s) you don’t need by deleting the
PackageName-versioninfo.egg file or directory (found in the installation
directory).

If you want to delete the currently installed version of a package (or
all versions of a package), you should first run:

     easy_install -m PackageName

This will ensure that Python doesn’t continue to search for a package
you’re planning to remove.  After you’ve done this, you can safely
delete the .egg files or directories, along with any scripts you wish to
remove.


File: setuptools.info,  Node: Managing Scripts,  Next: Executables and Launchers,  Prev: Uninstalling Packages,  Up: Using “Easy Install”

8.3.1.8 Managing Scripts
........................

Whenever you install, upgrade, or change versions of a package,
EasyInstall automatically installs the scripts for the selected package
version, unless you tell it not to with ‘-x’ or ‘--exclude-scripts’.  If
any scripts in the script directory have the same name, they are
overwritten.

Thus, you do not normally need to manually delete scripts for older
versions of a package, unless the newer version of the package does not
include a script of the same name.  However, if you are completely
uninstalling a package, you may wish to manually delete its scripts.

EasyInstall’s default behavior means that you can normally only run
scripts from one version of a package at a time.  If you want to keep
multiple versions of a script available, however, you can simply use the
‘--multi-version’ or ‘-m’ option, and rename the scripts that
EasyInstall creates.  This works because EasyInstall installs scripts as
short code stubs that ‘require()’ the matching version of the package
the script came from, so renaming the script has no effect on what it
executes.

For example, suppose you want to use two versions of the ‘rst2html’ tool
provided by the docutils(1) package.  You might first install one
version:

     easy_install -m docutils==0.3.9

then rename the ‘rst2html.py’ to ‘r2h_039’, and install another version:

     easy_install -m docutils==0.3.10

This will create another ‘rst2html.py’ script, this one using docutils
version 0.3.10 instead of 0.3.9.  You now have two scripts, each using a
different version of the package.  (Notice that we used ‘-m’ for both
installations, so that Python won’t lock us out of using anything but
the most recently-installed version of the package.)

   ---------- Footnotes ----------

   (1) http://docutils.sf.net/


File: setuptools.info,  Node: Executables and Launchers,  Next: Tips & Techniques,  Prev: Managing Scripts,  Up: Using “Easy Install”

8.3.1.9 Executables and Launchers
.................................

On Unix systems, scripts are installed with as natural files with a “#!”
header and no extension and they launch under the Python version
indicated in the header.

On Windows, there is no mechanism to “execute” files without extensions,
so EasyInstall provides two techniques to mirror the Unix behavior.  The
behavior is indicated by the SETUPTOOLS_LAUNCHER environment variable,
which may be “executable” (default) or “natural”.

Regardless of the technique used, the script(s) will be installed to a
Scripts directory (by default in the Python installation directory).  It
is recommended for EasyInstall that you ensure this directory is in the
PATH environment variable.  The easiest way to ensure the Scripts
directory is in the PATH is to run ‘Tools\Scripts\win_add2path.py’ from
the Python directory.

Note that instead of changing your ‘PATH’ to include the Python scripts
directory, you can also retarget the installation location for scripts
so they go on a directory that’s already on the ‘PATH’.  For more
information see *note Command-Line Options: ea. and *note Configuration
Files: f0.  During installation, pass command line options (such as
‘--script-dir’) to control where scripts will be installed.

* Menu:

* Windows Executable Launcher::
* Natural Script Launcher::


File: setuptools.info,  Node: Windows Executable Launcher,  Next: Natural Script Launcher,  Up: Executables and Launchers

8.3.1.10 Windows Executable Launcher
....................................

If the “executable” launcher is used, EasyInstall will create a ‘.exe’
launcher of the same name beside each installed script (including
‘easy_install’ itself).  These small .exe files launch the script of the
same name using the Python version indicated in the ‘#!’ header.

This behavior is currently default.  To force the use of executable
launchers, set ‘SETUPTOOLS_LAUNCHER’ to “executable”.


File: setuptools.info,  Node: Natural Script Launcher,  Prev: Windows Executable Launcher,  Up: Executables and Launchers

8.3.1.11 Natural Script Launcher
................................

EasyInstall also supports deferring to an external launcher such as
pylauncher(1) for launching scripts.  Enable this experimental
functionality by setting the ‘SETUPTOOLS_LAUNCHER’ environment variable
to “natural”.  EasyInstall will then install scripts as simple scripts
with a .pya (or .pyw) extension appended.  If these extensions are
associated with the pylauncher and listed in the PATHEXT environment
variable, these scripts can then be invoked simply and directly just
like any other executable.  This behavior may become default in a future
version.

EasyInstall uses the .pya extension instead of simply the typical ‘.py’
extension.  This distinct extension is necessary to prevent Python from
treating the scripts as importable modules (where name conflicts exist).
Current releases of pylauncher do not yet associate with .pya files by
default, but future versions should do so.

   ---------- Footnotes ----------

   (1) https://bitbucket.org/pypa/pylauncher


File: setuptools.info,  Node: Tips & Techniques,  Next: Password-Protected Sites,  Prev: Executables and Launchers,  Up: Using “Easy Install”

8.3.1.12 Tips & Techniques
..........................

* Menu:

* Multiple Python Versions::
* Restricting Downloads with --allow-hosts::
* Installing on Un-networked Machines::
* Packaging Others’ Projects As Eggs::
* Creating your own Package Index::


File: setuptools.info,  Node: Multiple Python Versions,  Next: Restricting Downloads with --allow-hosts,  Up: Tips & Techniques

8.3.1.13 Multiple Python Versions
.................................

EasyInstall installs itself under two names: ‘easy_install’ and
‘easy_install-N.N’, where ‘N.N’ is the Python version used to install
it.  Thus, if you install EasyInstall for both Python 3.2 and 2.7, you
can use the ‘easy_install-3.2’ or ‘easy_install-2.7’ scripts to install
packages for the respective Python version.

Setuptools also supplies easy_install as a runnable module which may be
invoked using ‘python -m easy_install’ for any Python with Setuptools
installed.


File: setuptools.info,  Node: Restricting Downloads with --allow-hosts,  Next: Installing on Un-networked Machines,  Prev: Multiple Python Versions,  Up: Tips & Techniques

8.3.1.14 Restricting Downloads with ‘--allow-hosts’
...................................................

You can use the ‘--allow-hosts’ (‘-H’) option to restrict what domains
EasyInstall will look for links and downloads on.  ‘--allow-hosts=None’
prevents downloading altogether.  You can also use wildcards, for
example to restrict downloading to hosts in your own intranet.  See the
section below on *note Command-Line Options: ea. for more details on the
‘--allow-hosts’ option.

By default, there are no host restrictions in effect, but you can change
this default by editing the appropriate *note configuration files: f0.
and adding:

     [easy_install]
     allow_hosts = *.myintranet.example.com,*.python.org

The above example would then allow downloads only from hosts in the
‘python.org’ and ‘myintranet.example.com’ domains, unless overridden on
the command line.


File: setuptools.info,  Node: Installing on Un-networked Machines,  Next: Packaging Others’ Projects As Eggs,  Prev: Restricting Downloads with --allow-hosts,  Up: Tips & Techniques

8.3.1.15 Installing on Un-networked Machines
............................................

Just copy the eggs or source packages you need to a directory on the
target machine, then use the ‘-f’ or ‘--find-links’ option to specify
that directory’s location.  For example:

     easy_install -H None -f somedir SomePackage

will attempt to install SomePackage using only eggs and source packages
found in ‘somedir’ and disallowing all remote access.  You should of
course make sure you have all of SomePackage’s dependencies available in
somedir.

If you have another machine of the same operating system and library
versions (or if the packages aren’t platform-specific), you can create
the directory of eggs using a command like this:

     easy_install -zmaxd somedir SomePackage

This will tell EasyInstall to put zipped eggs or source packages for
SomePackage and all its dependencies into ‘somedir’, without creating
any scripts or .pth files.  You can then copy the contents of ‘somedir’
to the target machine.  (‘-z’ means zipped eggs, ‘-m’ means
multi-version, which prevents .pth files from being used, ‘-a’ means to
copy all the eggs needed, even if they’re installed elsewhere on the
machine, and ‘-d’ indicates the directory to place the eggs in.)

You can also build the eggs from local development packages that were
installed with the ‘setup.py develop’ command, by including the ‘-l’
option, e.g.:

     easy_install -zmaxld somedir SomePackage

This will use locally-available source distributions to build the eggs.


File: setuptools.info,  Node: Packaging Others’ Projects As Eggs,  Next: Creating your own Package Index,  Prev: Installing on Un-networked Machines,  Up: Tips & Techniques

8.3.1.16 Packaging Others’ Projects As Eggs
...........................................

Need to distribute a package that isn’t published in egg form?  You can
use EasyInstall to build eggs for a project.  You’ll want to use the
‘--zip-ok’, ‘--exclude-scripts’, and possibly ‘--no-deps’ options (‘-z’,
‘-x’ and ‘-N’, respectively).  Use ‘-d’ or ‘--install-dir’ to specify
the location where you’d like the eggs placed.  By placing them in a
directory that is published to the web, you can then make the eggs
available for download, either in an intranet or to the internet at
large.

If someone distributes a package in the form of a single ‘.py’ file, you
can wrap it in an egg by tacking an ‘#egg=name-version’ suffix on the
file’s URL. So, something like this:

     easy_install -f "http://some.example.com/downloads/foo.py#egg=foo-1.0" foo

will install the package as an egg, and this:

     easy_install -zmaxd. \
         -f "http://some.example.com/downloads/foo.py#egg=foo-1.0" foo

will create a ‘.egg’ file in the current directory.


File: setuptools.info,  Node: Creating your own Package Index,  Prev: Packaging Others’ Projects As Eggs,  Up: Tips & Techniques

8.3.1.17 Creating your own Package Index
........................................

In addition to local directories and the Python Package Index,
EasyInstall can find download links on most any web page whose URL is
given to the ‘-f’ (‘--find-links’) option.  In the simplest case, you
can simply have a web page with links to eggs or Python source packages,
even an automatically generated directory listing (such as the Apache
web server provides).

If you are setting up an intranet site for package downloads, you may
want to configure the target machines to use your download site by
default, adding something like this to their *note configuration files:
f0.:

     [easy_install]
     find_links = http://mypackages.example.com/somedir/
                  http://turbogears.org/download/
                  http://peak.telecommunity.com/dist/

As you can see, you can list multiple URLs separated by whitespace,
continuing on multiple lines if necessary (as long as the subsequent
lines are indented.

If you are more ambitious, you can also create an entirely custom
package index or PyPI mirror.  See the ‘--index-url’ option under *note
Command-Line Options: ea, below, and also the section on *note Package
Index "API": fc.


File: setuptools.info,  Node: Password-Protected Sites,  Next: Using pypirc Credentials,  Prev: Tips & Techniques,  Up: Using “Easy Install”

8.3.1.18 Password-Protected Sites
.................................

If a site you want to download from is password-protected using HTTP
“Basic” authentication, you can specify your credentials in the URL,
like so:

     http://some_userid:some_password@some.example.com/some_path/

You can do this with both index page URLs and direct download URLs.  As
long as any HTML pages read by easy_install use `relative' links to
point to the downloads, the same user ID and password will be used to do
the downloading.


File: setuptools.info,  Node: Using pypirc Credentials,  Prev: Password-Protected Sites,  Up: Using “Easy Install”

8.3.1.19 Using .pypirc Credentials
..................................

In additional to supplying credentials in the URL, ‘easy_install’ will
also honor credentials if present in the .pypirc file.  Teams
maintaining a private repository of packages may already have defined
access credentials for uploading packages according to the distutils
documentation.  ‘easy_install’ will attempt to honor those if present.
Refer to the distutils documentation for Python 2.5 or later for details
on the syntax.

* Menu:

* Controlling Build Options::
* Editing and Viewing Source Packages::
* Dealing with Installation Conflicts::
* Compressed Installation::


File: setuptools.info,  Node: Controlling Build Options,  Next: Editing and Viewing Source Packages,  Up: Using pypirc Credentials

8.3.1.20 Controlling Build Options
..................................

EasyInstall respects standard distutils *note Configuration Files: f0,
so you can use them to configure build options for packages that it
installs from source.  For example, if you are on Windows using the
MinGW compiler, you can configure the default compiler by putting
something like this:

     [build]
     compiler = mingw32

into the appropriate distutils configuration file.  In fact, since this
is just normal distutils configuration, it will affect any builds using
that config file, not just ones done by EasyInstall.  For example, if
you add those lines to ‘distutils.cfg’ in the ‘distutils’ package
directory, it will be the default compiler for `all' packages you build.
See *note Configuration Files: f0. below for a list of the standard
configuration file locations, and links to more documentation on using
distutils configuration files.


File: setuptools.info,  Node: Editing and Viewing Source Packages,  Next: Dealing with Installation Conflicts,  Prev: Controlling Build Options,  Up: Using pypirc Credentials

8.3.1.21 Editing and Viewing Source Packages
............................................

Sometimes a package’s source distribution contains additional
documentation, examples, configuration files, etc., that are not part of
its actual code.  If you want to be able to examine these files, you can
use the ‘--editable’ option to EasyInstall, and EasyInstall will look
for a source distribution or Subversion URL for the package, then
download and extract it or check it out as a subdirectory of the
‘--build-directory’ you specify.  If you then wish to install the
package after editing or configuring it, you can do so by rerunning
EasyInstall with that directory as the target.

Note that using ‘--editable’ stops EasyInstall from actually building or
installing the package; it just finds, obtains, and possibly unpacks it
for you.  This allows you to make changes to the package if necessary,
and to either install it in development mode using ‘setup.py develop’
(if the package uses setuptools, that is), or by running ‘easy_install
projectdir’ (where ‘projectdir’ is the subdirectory EasyInstall created
for the downloaded package.

In order to use ‘--editable’ (‘-e’ for short), you `must' also supply a
‘--build-directory’ (‘-b’ for short).  The project will be placed in a
subdirectory of the build directory.  The subdirectory will have the
same name as the project itself, but in all-lowercase.  If a file or
directory of that name already exists, EasyInstall will print an error
message and exit.

Also, when using ‘--editable’, you cannot use URLs or filenames as
arguments.  You `must' specify project names (and optional version
requirements) so that EasyInstall knows what directory name(s) to
create.  If you need to force EasyInstall to use a particular URL or
filename, you should specify it as a ‘--find-links’ item (‘-f’ for
short), and then also specify the project name, e.g.:

     easy_install -eb ~/projects \
      -fhttp://prdownloads.sourceforge.net/ctypes/ctypes-0.9.6.tar.gz?download \
      ctypes==0.9.6


File: setuptools.info,  Node: Dealing with Installation Conflicts,  Next: Compressed Installation,  Prev: Editing and Viewing Source Packages,  Up: Using pypirc Credentials

8.3.1.22 Dealing with Installation Conflicts
............................................

(NOTE: As of 0.6a11, this section is obsolete; it is retained here only
so that people using older versions of EasyInstall can consult it.  As
of version 0.6a11, installation conflicts are handled automatically
without deleting the old or system-installed packages, and without
ignoring the issue.  Instead, eggs are automatically shifted to the
front of ‘sys.path’ using special code added to the ‘easy-install.pth’
file.  So, if you are using version 0.6a11 or better of setuptools, you
do not need to worry about conflicts, and the following issues do not
apply to you.)

EasyInstall installs distributions in a “managed” way, such that each
distribution can be independently activated or deactivated on
‘sys.path’.  However, packages that were not installed by EasyInstall
are “unmanaged”, in that they usually live all in one directory and
cannot be independently activated or deactivated.

As a result, if you are using EasyInstall to upgrade an existing
package, or to install a package with the same name as an existing
package, EasyInstall will warn you of the conflict.  (This is an
improvement over ‘setup.py install’, because the ‘distutils’ just
install new packages on top of old ones, possibly combining two
unrelated packages or leaving behind modules that have been deleted in
the newer version of the package.)

EasyInstall will stop the installation if it detects a conflict between
an existing, “unmanaged” package, and a module or package in any of the
distributions you’re installing.  It will display a list of all of the
existing files and directories that would need to be deleted for the new
package to be able to function correctly.  To proceed, you must manually
delete these conflicting files and directories and re-run EasyInstall.

Of course, once you’ve replaced all of your existing “unmanaged”
packages with versions managed by EasyInstall, you won’t have any more
conflicts to worry about!


File: setuptools.info,  Node: Compressed Installation,  Prev: Dealing with Installation Conflicts,  Up: Using pypirc Credentials

8.3.1.23 Compressed Installation
................................

EasyInstall tries to install packages in zipped form, if it can.
Zipping packages can improve Python’s overall import performance if
you’re not using the ‘--multi-version’ option, because Python processes
zipfile entries on ‘sys.path’ much faster than it does directories.

As of version 0.5a9, EasyInstall analyzes packages to determine whether
they can be safely installed as a zipfile, and then acts on its
analysis.  (Previous versions would not install a package as a zipfile
unless you used the ‘--zip-ok’ option.)

The current analysis approach is fairly conservative; it currently looks
for:

        * Any use of the ‘__file__’ or ‘__path__’ variables (which
          should be replaced with ‘pkg_resources’ API calls)

        * Possible use of ‘inspect’ functions that expect to manipulate
          source files (e.g.  ‘inspect.getsource()’)

        * Top-level modules that might be scripts used with ‘python -m’
          (Python 2.4)

If any of the above are found in the package being installed,
EasyInstall will assume that the package cannot be safely run from a
zipfile, and unzip it to a directory instead.  You can override this
analysis with the ‘-zip-ok’ flag, which will tell EasyInstall to install
the package as a zipfile anyway.  Or, you can use the ‘--always-unzip’
flag, in which case EasyInstall will always unzip, even if its analysis
says the package is safe to run as a zipfile.

Normally, however, it is simplest to let EasyInstall handle the
determination of whether to zip or unzip, and only specify overrides
when needed to work around a problem.  If you find you need to override
EasyInstall’s guesses, you may want to contact the package author and
the EasyInstall maintainers, so that they can make appropriate changes
in future versions.

(Note: If a package uses ‘setuptools’ in its setup script, the package
author has the option to declare the package safe or unsafe for zipped
usage via the ‘zip_safe’ argument to ‘setup()’.  If the package author
makes such a declaration, EasyInstall believes the package’s author and
does not perform its own analysis.  However, your command-line option,
if any, will still override the package author’s choice.)


File: setuptools.info,  Node: Reference Manual,  Prev: Using “Easy Install”,  Up: Easy Install

8.3.2 Reference Manual
----------------------

* Menu:

* Configuration Files::
* Command-Line Options::
* Custom Installation Locations::
* Package Index “API”::


File: setuptools.info,  Node: Configuration Files,  Next: Command-Line Options,  Up: Reference Manual

8.3.2.1 Configuration Files
...........................

(New in 0.4a2)

You may specify default options for EasyInstall using the standard
distutils configuration files, under the command heading ‘easy_install’.
EasyInstall will look first for a ‘setup.cfg’ file in the current
directory, then a ‘~/.pydistutils.cfg’ or ‘$HOME\\pydistutils.cfg’ (on
Unix-like OSes and Windows, respectively), and finally a ‘distutils.cfg’
file in the ‘distutils’ package directory.  Here’s a simple example:

     [easy_install]

     # set the default location to install packages
     install_dir = /home/me/lib/python

     # Notice that indentation can be used to continue an option
     # value; this is especially useful for the "--find-links"
     # option, which tells easy_install to use download links on
     # these pages before consulting PyPI:
     #
     find_links = http://sqlobject.org/
                  http://peak.telecommunity.com/dist/

In addition to accepting configuration for its own options under
‘[easy_install]’, EasyInstall also respects defaults specified for other
distutils commands.  For example, if you don’t set an ‘install_dir’ for
‘[easy_install]’, but `have' set an ‘install_lib’ for the ‘[install]’
command, this will become EasyInstall’s default installation directory.
Thus, if you are already using distutils configuration files to set
default install locations, build options, etc., EasyInstall will respect
your existing settings until and unless you override them explicitly in
an ‘[easy_install]’ section.

For more information, see also the current Python documentation on the
use and location of distutils configuration files(1).

Notice that ‘easy_install’ will use the ‘setup.cfg’ from the current
working directory only if it was triggered from ‘setup.py’ through the
‘install_requires’ option.  The standalone command will not use that
file.

   ---------- Footnotes ----------

   (1) https://docs.python.org/install/index.html#inst-config-files


File: setuptools.info,  Node: Command-Line Options,  Next: Custom Installation Locations,  Prev: Configuration Files,  Up: Reference Manual

8.3.2.2 Command-Line Options
............................

‘--zip-ok, -z’

     Install all packages as zip files, even if they are marked as
     unsafe for running as a zipfile.  This can be useful when
     EasyInstall’s analysis of a non-setuptools package is too
     conservative, but keep in mind that the package may not work
     correctly.  (Changed in 0.5a9; previously this option was required
     in order for zipped installation to happen at all.)

‘--always-unzip, -Z’

     Don’t install any packages as zip files, even if the packages are
     marked as safe for running as a zipfile.  This can be useful if a
     package does something unsafe, but not in a way that EasyInstall
     can easily detect.  EasyInstall’s default analysis is currently
     very conservative, however, so you should only use this option if
     you’ve had problems with a particular package, and `after'
     reporting the problem to the package’s maintainer and to the
     EasyInstall maintainers.

     (Note: the ‘-z/-Z’ options only affect the installation of
     newly-built or downloaded packages that are not already installed
     in the target directory; if you want to convert an existing
     installed version from zipped to unzipped or vice versa, you’ll
     need to delete the existing version first, and re-run EasyInstall.)

‘--multi-version, -m’

     “Multi-version” mode.  Specifying this option prevents
     ‘easy_install’ from adding an ‘easy-install.pth’ entry for the
     package being installed, and if an entry for any version the
     package already exists, it will be removed upon successful
     installation.  In multi-version mode, no specific version of the
     package is available for importing, unless you use
     ‘pkg_resources.require()’ to put it on ‘sys.path’.  This can be as
     simple as:

          from pkg_resources import require
          require("SomePackage", "OtherPackage", "MyPackage")

     which will put the latest installed version of the specified
     packages on ‘sys.path’ for you.  (For more advanced uses, like
     selecting specific versions and enabling optional dependencies, see
     the ‘pkg_resources’ API doc.)

     Changed in 0.6a10: this option is no longer silently enabled when
     installing to a non-PYTHONPATH, non-“site” directory.  You must
     always explicitly use this option if you want it to be active.

‘--upgrade, -U’ (New in 0.5a4)

     By default, EasyInstall only searches online if a project/version
     requirement can’t be met by distributions already installed on
     sys.path or the installation directory.  However, if you supply the
     ‘--upgrade’ or ‘-U’ flag, EasyInstall will always check the package
     index and ‘--find-links’ URLs before selecting a version to
     install.  In this way, you can force EasyInstall to use the latest
     available version of any package it installs (subject to any
     version requirements that might exclude such later versions).

‘--install-dir=DIR, -d DIR’

     Set the installation directory.  It is up to you to ensure that
     this directory is on ‘sys.path’ at runtime, and to use
     ‘pkg_resources.require()’ to enable the installed package(s) that
     you need.

     (New in 0.4a2) If this option is not directly specified on the
     command line or in a distutils configuration file, the distutils
     default installation location is used.  Normally, this would be the
     ‘site-packages’ directory, but if you are using distutils
     configuration files, setting things like ‘prefix’ or ‘install_lib’,
     then those settings are taken into account when computing the
     default installation directory, as is the ‘--prefix’ option.

‘--script-dir=DIR, -s DIR’

     Set the script installation directory.  If you don’t supply this
     option (via the command line or a configuration file), but you
     `have' supplied an ‘--install-dir’ (via command line or config
     file), then this option defaults to the same directory, so that the
     scripts will be able to find their associated package installation.
     Otherwise, this setting defaults to the location where the
     distutils would normally install scripts, taking any distutils
     configuration file settings into account.

‘--exclude-scripts, -x’

     Don’t install scripts.  This is useful if you need to install
     multiple versions of a package, but do not want to reset the
     version that will be run by scripts that are already installed.

‘--user’ (New in 0.6.11)

     Use the user-site-packages as specified in PEP 370(1) instead of
     the global site-packages.

‘--always-copy, -a’ (New in 0.5a4)

     Copy all needed distributions to the installation directory, even
     if they are already present in a directory on sys.path.  In older
     versions of EasyInstall, this was the default behavior, but now you
     must explicitly request it.  By default, EasyInstall will no longer
     copy such distributions from other sys.path directories to the
     installation directory, unless you explicitly gave the
     distribution’s filename on the command line.

     Note that as of 0.6a10, using this option excludes “system” and
     “development” eggs from consideration because they can’t be
     reliably copied.  This may cause EasyInstall to choose an older
     version of a package than what you expected, or it may cause
     downloading and installation of a fresh copy of something that’s
     already installed.  You will see warning messages for any eggs that
     EasyInstall skips, before it falls back to an older version or
     attempts to download a fresh copy.

‘--find-links=URLS_OR_FILENAMES, -f URLS_OR_FILENAMES’

     Scan the specified “download pages” or directories for direct links
     to eggs or other distributions.  Any existing file or directory
     names or direct download URLs are immediately added to
     EasyInstall’s search cache, and any indirect URLs (ones that don’t
     point to eggs or other recognized archive formats) are added to a
     list of additional places to search for download links.  As soon as
     EasyInstall has to go online to find a package (either because it
     doesn’t exist locally, or because ‘--upgrade’ or ‘-U’ was used),
     the specified URLs will be downloaded and scanned for additional
     direct links.

     Eggs and archives found by way of ‘--find-links’ are only
     downloaded if they are needed to meet a requirement specified on
     the command line; links to unneeded packages are ignored.

     If all requested packages can be found using links on the specified
     download pages, the Python Package Index will not be consulted
     unless you also specified the ‘--upgrade’ or ‘-U’ option.

     (Note: if you want to refer to a local HTML file containing links,
     you must use a ‘file:’ URL, as filenames that do not refer to a
     directory, egg, or archive are ignored.)

     You may specify multiple URLs or file/directory names with this
     option, separated by whitespace.  Note that on the command line,
     you will probably have to surround the URL list with quotes, so
     that it is recognized as a single option value.  You can also
     specify URLs in a configuration file; see *note Configuration
     Files: f0, above.

     Changed in 0.6a10: previously all URLs and directories passed to
     this option were scanned as early as possible, but from 0.6a10 on,
     only directories and direct archive links are scanned immediately;
     URLs are not retrieved unless a package search was already going to
     go online due to a package not being available locally, or due to
     the use of the ‘--update’ or ‘-U’ option.

‘--no-find-links’ Blocks the addition of any link.

     This parameter is useful if you want to avoid adding links defined
     in a project easy_install is installing (whether it’s a requested
     project or a dependency).  When used, ‘--find-links’ is ignored.

     Added in Distribute 0.6.11 and Setuptools 0.7.

‘--index-url=URL, -i URL’ (New in 0.4a1; default changed in 0.6c7)

     Specifies the base URL of the Python Package Index.  The default is
     ‘https://pypi.org/simple/’ if not specified.  When a package is
     requested that is not locally available or linked from a
     ‘--find-links’ download page, the package index will be searched
     for download pages for the needed package, and those download pages
     will be searched for links to download an egg or source
     distribution.

‘--editable, -e’ (New in 0.6a1)

     Only find and download source distributions for the specified
     projects, unpacking them to subdirectories of the specified
     ‘--build-directory’.  EasyInstall will not actually build or
     install the requested projects or their dependencies; it will just
     find and extract them for you.  See *note Editing and Viewing
     Source Packages: ef. above for more details.

‘--build-directory=DIR, -b DIR’ (UPDATED in 0.6a1)

     Set the directory used to build source packages.  If a package is
     built from a source distribution or checkout, it will be extracted
     to a subdirectory of the specified directory.  The subdirectory
     will have the same name as the extracted distribution’s project,
     but in all-lowercase.  If a file or directory of that name already
     exists in the given directory, a warning will be printed to the
     console, and the build will take place in a temporary directory
     instead.

     This option is most useful in combination with the ‘--editable’
     option, which forces EasyInstall to `only' find and extract (but
     not build and install) source distributions.  See *note Editing and
     Viewing Source Packages: ef, above, for more information.

‘--verbose, -v, --quiet, -q’ (New in 0.4a4)

     Control the level of detail of EasyInstall’s progress messages.
     The default detail level is “info”, which prints information only
     about relatively time-consuming operations like running a setup
     script, unpacking an archive, or retrieving a URL. Using ‘-q’ or
     ‘--quiet’ drops the detail level to “warn”, which will only display
     installation reports, warnings, and errors.  Using ‘-v’ or
     ‘--verbose’ increases the detail level to include individual
     file-level operations, link analysis messages, and distutils
     messages from any setup scripts that get run.  If you include the
     ‘-v’ option more than once, the second and subsequent uses are
     passed down to any setup scripts, increasing the verbosity of their
     reporting as well.

‘--dry-run, -n’ (New in 0.4a4)

     Don’t actually install the package or scripts.  This option is
     passed down to any setup scripts run, so packages should not
     actually build either.  This does `not' skip downloading, nor does
     it skip extracting source distributions to a temporary/build
     directory.

‘--optimize=LEVEL’, ‘-O LEVEL’ (New in 0.4a4)

     If you are installing from a source distribution, and are `not'
     using the ‘--zip-ok’ option, this option controls the optimization
     level for compiling installed ‘.py’ files to ‘.pyo’ files.  It does
     not affect the compilation of modules contained in ‘.egg’ files,
     only those in ‘.egg’ directories.  The optimization level can be
     set to 0, 1, or 2; the default is 0 (unless it’s set under
     ‘install’ or ‘install_lib’ in one of your distutils configuration
     files).

‘--record=FILENAME’ (New in 0.5a4)

     Write a record of all installed files to FILENAME. This is
     basically the same as the same option for the standard distutils
     “install” command, and is included for compatibility with tools
     that expect to pass this option to “setup.py install”.

‘--site-dirs=DIRLIST, -S DIRLIST’ (New in 0.6a1)

     Specify one or more custom “site” directories (separated by
     commas).  “Site” directories are directories where ‘.pth’ files are
     processed, such as the main Python ‘site-packages’ directory.  As
     of 0.6a10, EasyInstall automatically detects whether a given
     directory processes ‘.pth’ files (or can be made to do so), so you
     should not normally need to use this option.  It is is now only
     necessary if you want to override EasyInstall’s judgment and force
     an installation directory to be treated as if it supported ‘.pth’
     files.

‘--no-deps, -N’ (New in 0.6a6)

     Don’t install any dependencies.  This is intended as a convenience
     for tools that wrap eggs in a platform-specific packaging system.
     (We don’t recommend that you use it for anything else.)

‘--allow-hosts=PATTERNS, -H PATTERNS’ (New in 0.6a6)

     Restrict downloading and spidering to hosts matching the specified
     glob patterns.  E.g.  ‘-H *.python.org’ restricts web access so
     that only packages listed and downloadable from machines in the
     ‘python.org’ domain.  The glob patterns must match the `entire'
     user/host/port section of the target URL(s).  For example,
     ‘*.python.org’ will NOT accept a URL like ‘http://python.org/foo’
     or ‘http://www.python.org:8080/’.  Multiple patterns can be
     specified by separating them with commas.  The default pattern is
     ‘*’, which matches anything.

     In general, this option is mainly useful for blocking EasyInstall’s
     web access altogether (e.g.  ‘-Hlocalhost’), or to restrict it to
     an intranet or other trusted site.  EasyInstall will do the best it
     can to satisfy dependencies given your host restrictions, but of
     course can fail if it can’t find suitable packages.  EasyInstall
     displays all blocked URLs, so that you can adjust your
     ‘--allow-hosts’ setting if it is more strict than you intended.
     Some sites may wish to define a restrictive default setting for
     this option in their *note configuration files: f0, and then
     manually override the setting on the command line as needed.

‘--prefix=DIR’ (New in 0.6a10)

     Use the specified directory as a base for computing the default
     installation and script directories.  On Windows, the resulting
     default directories will be ‘prefix\\Lib\\site-packages’ and
     ‘prefix\\Scripts’, while on other platforms the defaults will be
     ‘prefix/lib/python2.X/site-packages’ (with the appropriate version
     substituted) for libraries and ‘prefix/bin’ for scripts.

     Note that the ‘--prefix’ option only sets the `default'
     installation and script directories, and does not override the ones
     set on the command line or in a configuration file.

‘--local-snapshots-ok, -l’ (New in 0.6c6)

     Normally, EasyInstall prefers to only install `released' versions
     of projects, not in-development ones, because such projects may not
     have a currently-valid version number.  So, it usually only
     installs them when their ‘setup.py’ directory is explicitly passed
     on the command line.

     However, if this option is used, then any in-development projects
     that were installed using the ‘setup.py develop’ command, will be
     used to build eggs, effectively upgrading the “in-development”
     project to a snapshot release.  Normally, this option is used only
     in conjunction with the ‘--always-copy’ option to create a
     distributable snapshot of every egg needed to run an application.

     Note that if you use this option, you must make sure that there is
     a valid version number (such as an SVN revision number tag) for any
     in-development projects that may be used, as otherwise EasyInstall
     may not be able to tell what version of the project is “newer” when
     future installations or upgrades are attempted.

   ---------- Footnotes ----------

   (1) https://www.python.org/dev/peps/pep-0370


File: setuptools.info,  Node: Custom Installation Locations,  Next: Package Index “API”,  Prev: Command-Line Options,  Up: Reference Manual

8.3.2.3 Custom Installation Locations
.....................................

By default, EasyInstall installs python packages into Python’s main
‘site-packages’ directory, and manages them using a custom ‘.pth’ file
in that same directory.

Very often though, a user or developer wants ‘easy_install’ to install
and manage python packages in an alternative location, usually for one
of 3 reasons:

  1. They don’t have access to write to the main Python site-packages
     directory.

  2. They want a user-specific stash of packages, that is not visible to
     other users.

  3. They want to isolate a set of packages to a specific python
     application, usually to minimize the possibility of version
     conflicts.

Historically, there have been many approaches to achieve custom
installation.  The following section lists only the easiest and most
relevant approaches (1).

*note Use the "–user" option: 104.

*note Use the "–user" option and customize "PYTHONUSERBASE": 105.

*note Use "virtualenv": 106.

* Menu:

* Use the “–user” option::
* Use the “–user” option and customize “PYTHONUSERBASE”::
* Use “virtualenv”::

   ---------- Footnotes ----------

   (1) (1) There are older ways to achieve custom installation using
various ‘easy_install’ and ‘setup.py install’ options, combined with
‘PYTHONPATH’ and/or ‘PYTHONUSERBASE’ alterations, but all of these are
effectively deprecated by the User scheme brought in by PEP-370
(http://www.python.org/dev/peps/pep-0370/).


File: setuptools.info,  Node: Use the “–user” option,  Next: Use the “–user” option and customize “PYTHONUSERBASE”,  Up: Custom Installation Locations

8.3.2.4 Use the “–user” option
..............................

Python provides a User scheme for installation, which means that all
python distributions support an alternative install location that is
specific to a user (1).  The Default location for each OS is explained
in the python documentation for the ‘site.USER_BASE’ variable.  This
mode of installation can be turned on by specifying the ‘--user’ option
to ‘setup.py install’ or ‘easy_install’.  This approach serves the need
to have a user-specific stash of packages.

   ---------- Footnotes ----------

   (1) (3) Prior to the User scheme, there was the Home scheme, which is
still available, but requires more effort than the User scheme to get
packages recognized.


File: setuptools.info,  Node: Use the “–user” option and customize “PYTHONUSERBASE”,  Next: Use “virtualenv”,  Prev: Use the “–user” option,  Up: Custom Installation Locations

8.3.2.5 Use the “–user” option and customize “PYTHONUSERBASE”
.............................................................

The User scheme install location can be customized by setting the
‘PYTHONUSERBASE’ environment variable, which updates the value of
‘site.USER_BASE’.  To isolate packages to a specific application, simply
set the OS environment of that application to a specific value of
‘PYTHONUSERBASE’, that contains just those packages.


File: setuptools.info,  Node: Use “virtualenv”,  Prev: Use the “–user” option and customize “PYTHONUSERBASE”,  Up: Custom Installation Locations

8.3.2.6 Use “virtualenv”
........................

“virtualenv” is a 3rd-party python package that effectively “clones” a
python installation, thereby creating an isolated location to install
packages.  The evolution of “virtualenv” started before the existence of
the User installation scheme.  “virtualenv” provides a version of
‘easy_install’ that is scoped to the cloned python install and is used
in the normal way.  “virtualenv” does offer various features that the
User installation scheme alone does not provide, e.g.  the ability to
hide the main python site-packages.

Please refer to the virtualenv(1) documentation for more details.

   ---------- Footnotes ----------

   (1) https://pypi.org/project/virtualenv/


File: setuptools.info,  Node: Package Index “API”,  Prev: Custom Installation Locations,  Up: Reference Manual

8.3.2.7 Package Index “API”
...........................

Custom package indexes (and PyPI) must follow the following rules for
EasyInstall to be able to look up and download packages:

  1. Except where stated otherwise, “pages” are HTML or XHTML, and
     “links” refer to ‘href’ attributes.

  2. Individual project version pages’ URLs must be of the form
     ‘base/projectname/version’, where ‘base’ is the package index’s
     base URL.

  3. Omitting the ‘/version’ part of a project page’s URL (but keeping
     the trailing ‘/’) should result in a page that is either:

       a. The single active version of that project, as though the
          version had been explicitly included, OR

       b. A page with links to all of the active version pages for that
          project.

  4. Individual project version pages should contain direct links to
     downloadable distributions where possible.  It is explicitly
     permitted for a project’s “long_description” to include URLs, and
     these should be formatted as HTML links by the package index, as
     EasyInstall does no special processing to identify what parts of a
     page are index-specific and which are part of the project’s
     supplied description.

  5. Where available, MD5 information should be added to download URLs
     by appending a fragment identifier of the form ‘#md5=...’, where
     ‘...’ is the 32-character hex MD5 digest.  EasyInstall will verify
     that the downloaded file’s MD5 digest matches the given value.

  6. Individual project version pages should identify any “homepage” or
     “download” URLs using ‘rel="homepage"’ and ‘rel="download"’
     attributes on the HTML elements linking to those URLs.  Use of
     these attributes will cause EasyInstall to always follow the
     provided links, unless it can be determined by inspection that they
     are downloadable distributions.  If the links are not to
     downloadable distributions, they are retrieved, and if they are
     HTML, they are scanned for download links.  They are `not' scanned
     for additional “homepage” or “download” links, as these are only
     processed for pages that are part of a package index site.

  7. The root URL of the index, if retrieved with a trailing ‘/’, must
     result in a page containing links to `all' projects’ active version
     pages.

     (Note: This requirement is a workaround for the absence of
     case-insensitive ‘safe_name()’ matching of project names in URL
     paths.  If project names are matched in this fashion (e.g.  via the
     PyPI server, mod_rewrite, or a similar mechanism), then it is not
     necessary to include this all-packages listing page.)

  8. If a package index is accessed via a ‘file://’ URL, then
     EasyInstall will automatically use ‘index.html’ files, if present,
     when trying to read a directory with a trailing ‘/’ on the URL.


File: setuptools.info,  Node: Porting from Distutils,  Next: “Eggsecutable” Scripts,  Prev: Easy Install,  Up: Guides on backward compatibility & deprecated practice

8.4 Porting from Distutils
==========================

Setuptools and the PyPA have a stated goal(1) to make Setuptools the
reference API for distutils.

Since the 49.1.2 release, Setuptools includes a local, vendored copy of
distutils (from late copies of CPython) that is disabled by default.  To
enable the use of this copy of distutils when invoking setuptools, set
the enviroment variable:

     SETUPTOOLS_USE_DISTUTILS=local

This behavior is planned to become the default.

* Menu:

* Prefer Setuptools::

   ---------- Footnotes ----------

   (1) https://github.com/pypa/packaging-problems/issues/127


File: setuptools.info,  Node: Prefer Setuptools,  Up: Porting from Distutils

8.4.1 Prefer Setuptools
-----------------------

As Distutils is deprecated, any usage of functions or objects from
distutils is similarly discouraged, and Setuptools aims to replace or
deprecate all such uses.  This section describes the recommended
replacements.

‘distutils.core.setup’ → ‘setuptools.setup’

‘distutils.cmd.Command’ → ‘setuptools.Command’

‘distutils.log’ → (no replacement yet)

‘distutils.version.*’ → ‘packaging.version.*’

If a project relies on uses of ‘distutils’ that do not have a suitable
replacement above, please search the Setuptools issue tracker(1) and
file a request, describing the use-case so that Setuptools’ maintainers
can investigate.  Please provide enough detail to help the maintainers
understand how distutils is used, what value it provides, and why that
behavior should be supported.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/


File: setuptools.info,  Node: “Eggsecutable” Scripts,  Prev: Porting from Distutils,  Up: Guides on backward compatibility & deprecated practice

8.5 “Eggsecutable” Scripts
==========================

Deprecated since version 45.3.0.

Occasionally, there are situations where it’s desirable to make an
‘.egg’ file directly executable.  You can do this by including an entry
point such as the following:

     setup(
         # other arguments here...
         entry_points={
             "setuptools.installation": [
                 "eggsecutable = my_package.some_module:main_func",
             ]
         }
     )

Any eggs built from the above setup script will include a short
executable prelude that imports and calls ‘main_func()’ from
‘my_package.some_module’.  The prelude can be run on Unix-like platforms
(including Mac and Linux) by invoking the egg with ‘/bin/sh’, or by
enabling execute permissions on the ‘.egg’ file.  For the executable
prelude to run, the appropriate version of Python must be available via
the ‘PATH’ environment variable, under its “long” name.  That is, if the
egg is built for Python 2.3, there must be a ‘python2.3’ executable
present in a directory on ‘PATH’.

IMPORTANT NOTE: Eggs with an “eggsecutable” header cannot be renamed, or
invoked via symlinks.  They `must' be invoked using their original
filename, in order to ensure that, once running, ‘pkg_resources’ will
know what project and version is in use.  The header script will check
this and exit with an error if the ‘.egg’ file has been renamed or is
invoked via a symlink that changes its base name.


File: setuptools.info,  Node: History<2>,  Next: Credits,  Prev: Guides on backward compatibility & deprecated practice,  Up: Top

9 History
*********

* Menu:

* v50.3.2: v50 3 2.
* v50.3.1: v50 3 1.
* v50.3.0: v50 3 0.
* v50.2.0: v50 2 0.
* v50.1.0: v50 1 0.
* v50.0.3: v50 0 3.
* v50.0.2: v50 0 2.
* v50.0.1: v50 0 1.
* v50.0.0: v50 0 0.
* v49.6.0: v49 6 0.
* v49.5.0: v49 5 0.
* v49.4.0: v49 4 0.
* v49.3.2: v49 3 2.
* v49.3.1: v49 3 1.
* v49.3.0: v49 3 0.
* v49.2.1: v49 2 1.
* v49.2.0: v49 2 0.
* v49.1.3: v49 1 3.
* v49.1.2: v49 1 2.
* v49.1.1: v49 1 1.
* v49.0.1: v49 0 1.
* v49.1.0: v49 1 0.
* v49.0.0: v49 0 0.
* v48.0.0: v48 0 0.
* v47.3.2: v47 3 2.
* v47.3.1: v47 3 1.
* v47.3.0: v47 3 0.
* v47.2.0: v47 2 0.
* v47.1.1: v47 1 1.
* v44.1.1: v44 1 1.
* v47.1.0: v47 1 0.
* v47.0.0: v47 0 0.
* v46.4.0: v46 4 0.
* v46.3.1: v46 3 1.
* v46.3.0: v46 3 0.
* v46.2.0: v46 2 0.
* v46.1.3: v46 1 3.
* v46.1.2: v46 1 2.
* v46.1.1: v46 1 1.
* v46.1.0: v46 1 0.
* v44.1.0: v44 1 0.
* v46.0.0: v46 0 0.
* v45.3.0: v45 3 0.
* v45.2.0: v45 2 0.
* v45.1.0: v45 1 0.
* v45.0.0: v45 0 0.
* v44.0.0: v44 0 0.
* v43.0.0: v43 0 0.
* v42.0.2: v42 0 2.
* v42.0.1: v42 0 1.
* v42.0.0: v42 0 0.
* v41.6.0: v41 6 0.
* v41.5.1: v41 5 1.
* v41.5.0: v41 5 0.
* v41.4.0: v41 4 0.
* v41.3.0: v41 3 0.
* v41.2.0: v41 2 0.
* v41.1.0: v41 1 0.
* v41.0.1: v41 0 1.
* v41.0.0: v41 0 0.
* v40.9.0: v40 9 0.
* v40.8.0: v40 8 0.
* v40.7.3: v40 7 3.
* v40.7.2: v40 7 2.
* v40.7.1: v40 7 1.
* v40.7.0: v40 7 0.
* v40.6.3: v40 6 3.
* v40.6.2: v40 6 2.
* v40.6.1: v40 6 1.
* v40.6.0: v40 6 0.
* v40.5.0: v40 5 0.
* v40.4.3: v40 4 3.
* v40.4.2: v40 4 2.
* v40.4.1: v40 4 1.
* v40.4.0: v40 4 0.
* v40.3.0: v40 3 0.
* v40.2.0: v40 2 0.
* v40.1.1: v40 1 1.
* v40.1.0: v40 1 0.
* v40.0.0: v40 0 0.
* v39.2.0: v39 2 0.
* v39.1.0: v39 1 0.
* v39.0.1: v39 0 1.
* v39.0.0: v39 0 0.
* v38.7.0: v38 7 0.
* v38.6.1: v38 6 1.
* v38.6.0: v38 6 0.
* v38.5.2: v38 5 2.
* v38.5.1: v38 5 1.
* v38.5.0: v38 5 0.
* v38.4.1: v38 4 1.
* v38.4.0: v38 4 0.
* v38.3.0: v38 3 0.
* v38.2.5: v38 2 5.
* v38.2.4: v38 2 4.
* v38.2.3: v38 2 3.
* v38.2.2: v38 2 2.
* v38.2.1: v38 2 1.
* v38.2.0: v38 2 0.
* v38.1.0: v38 1 0.
* v38.0.0: v38 0 0.
* v37.0.0: v37 0 0.
* v36.8.0: v36 8 0.
* v36.7.3: v36 7 3.
* v36.7.2: v36 7 2.
* v36.7.1: v36 7 1.
* v36.7.0: v36 7 0.
* v36.6.1: v36 6 1.
* v36.6.0: v36 6 0.
* v36.5.0: v36 5 0.
* v36.4.0: v36 4 0.
* v36.3.0: v36 3 0.
* v36.2.7: v36 2 7.
* v36.2.6: v36 2 6.
* v36.2.5: v36 2 5.
* v36.2.4: v36 2 4.
* v36.2.3: v36 2 3.
* v36.2.2: v36 2 2.
* v36.2.1: v36 2 1.
* v36.2.0: v36 2 0.
* v36.1.1: v36 1 1.
* v36.1.0: v36 1 0.
* v36.0.1: v36 0 1.
* v36.0.0: v36 0 0.
* v35.0.2: v35 0 2.
* v35.0.1: v35 0 1.
* v35.0.0: v35 0 0.
* v34.4.1: v34 4 1.
* v34.4.0: v34 4 0.
* v34.3.3: v34 3 3.
* v34.3.2: v34 3 2.
* v34.3.1: v34 3 1.
* v34.3.0: v34 3 0.
* v34.2.0: v34 2 0.
* v34.1.1: v34 1 1.
* v34.1.0: v34 1 0.
* v34.0.3: v34 0 3.
* v34.0.2: v34 0 2.
* v34.0.1: v34 0 1.
* v34.0.0: v34 0 0.
* v33.1.1: v33 1 1.
* v33.1.0: v33 1 0.
* v33.0.0: v33 0 0.
* v32.3.1: v32 3 1.
* v32.3.0: v32 3 0.
* v32.2.0: v32 2 0.
* v32.1.3: v32 1 3.
* v32.1.2: v32 1 2.
* v32.1.1: v32 1 1.
* v32.1.0: v32 1 0.
* v32.0.0: v32 0 0.
* v31.0.1: v31 0 1.
* v31.0.0: v31 0 0.
* v30.4.0: v30 4 0.
* v30.3.0: v30 3 0.
* v30.2.1: v30 2 1.
* v30.2.0: v30 2 0.
* v30.1.0: v30 1 0.
* v30.0.0: v30 0 0.
* v29.0.1: v29 0 1.
* v29.0.0: v29 0 0.
* v28.8.0: v28 8 0.
* v28.7.1: v28 7 1.
* v28.7.0: v28 7 0.
* v28.6.1: v28 6 1.
* v28.6.0: v28 6 0.
* v28.5.0: v28 5 0.
* v28.4.0: v28 4 0.
* v28.3.0: v28 3 0.
* v28.1.0: v28 1 0.
* v28.0.0: v28 0 0.
* v27.3.1: v27 3 1.
* v27.3.0: v27 3 0.
* v27.2.0: v27 2 0.
* v27.1.2: v27 1 2.
* v27.1.1: v27 1 1.
* v27.1.0: v27 1 0.
* v27.0.0: v27 0 0.
* v26.1.1: v26 1 1.
* v26.1.0: v26 1 0.
* v26.0.0: v26 0 0.
* v25.4.0: v25 4 0.
* v25.3.0: v25 3 0.
* v25.2.0: v25 2 0.
* v25.1.6: v25 1 6.
* v25.1.5: v25 1 5.
* v25.1.4: v25 1 4.
* v25.1.3: v25 1 3.
* v25.1.2: v25 1 2.
* v25.1.1: v25 1 1.
* v25.1.0: v25 1 0.
* v25.0.2: v25 0 2.
* v25.0.1: v25 0 1.
* v25.0.0: v25 0 0.
* v24.3.1: v24 3 1.
* v24.3.0: v24 3 0.
* v24.2.1: v24 2 1.
* v24.2.0: v24 2 0.
* v24.1.1: v24 1 1.
* v24.1.0: v24 1 0.
* v24.0.3: v24 0 3.
* v24.0.2: v24 0 2.
* v24.0.1: v24 0 1.
* v24.0.0: v24 0 0.
* v23.2.1: v23 2 1.
* v23.1.0: v23 1 0.
* v23.0.0: v23 0 0.
* v22.0.5: v22 0 5.
* v22.0.4: v22 0 4.
* v22.0.3: v22 0 3.
* v22.0.2: v22 0 2.
* v22.0.1: v22 0 1.
* v22.0.0: v22 0 0.
* v21.2.2: v21 2 2.
* v21.2.1: v21 2 1.
* v21.2.0: v21 2 0.
* v21.1.0: v21 1 0.
* v21.0.0: v21 0 0.
* v20.10.0: v20 10 0.
* v20.9.0: v20 9 0.
* v20.8.1: v20 8 1.
* v20.8.0: v20 8 0.
* v20.7.0: v20 7 0.
* v20.6.8: v20 6 8.
* v20.6.7: v20 6 7.
* v20.6.6: v20 6 6.
* v20.6.0: v20 6 0.
* 20.5: 20 5.
* 20.4: 20 4.
* 20.3.1: 20 3 1.
* 20.3: 20 3.
* 20.2.2: 20 2 2.
* 20.2.1: 20 2 1.
* 20.2: 20 2.
* 20.1.1: 20 1 1.
* 20.1: 20 1.
* 20.0: 20 0.
* 19.7: 19 7.
* 19.6.2: 19 6 2.
* 19.6.1: 19 6 1.
* 19.6: 19 6.
* 19.5: 19 5.
* 19.4.1: 19 4 1.
* 19.4: 19 4.
* 19.3: 19 3.
* 19.2: 19 2.
* 19.1.1: 19 1 1.
* 19.1: 19 1.
* 19.0: 19 0.
* 18.8.1: 18 8 1.
* 18.8: 18 8.
* 18.7.1: 18 7 1.
* 18.7: 18 7.
* 18.6.1: 18 6 1.
* 18.6: 18 6.
* 18.5: 18 5.
* 18.4: 18 4.
* 18.3.2: 18 3 2.
* 18.3.1: 18 3 1.
* 18.3: 18 3.
* 18.2: 18 2.
* 18.1: 18 1.
* 18.0.1: 18 0 1.
* 18.0: 18 0.
* 17.1.1: 17 1 1.
* 17.1: 17 1.
* 17.0: 17 0.
* 16.0: 16 0.
* 15.2: 15 2.
* 15.1: 15 1.
* 15.0: 15 0.
* 14.3.1: 14 3 1.
* 14.3: 14 3.
* 14.2: 14 2.
* 14.1.1: 14 1 1.
* 14.1: 14 1.
* 14.0: 14 0.
* 13.0.2: 13 0 2.
* 13.0.1: 13 0 1.
* 13.0: 13 0.
* 12.4: 12 4.
* 12.3: 12 3.
* 12.2: 12 2.
* 12.1: 12 1.
* 12.0.5: 12 0 5.
* 12.0.4: 12 0 4.
* 12.0.3: 12 0 3.
* 12.0.2: 12 0 2.
* 12.0.1: 12 0 1.
* 12.0: 12 0.
* 11.3.1: 11 3 1.
* 11.3: 11 3.
* 11.2: 11 2.
* 11.1: 11 1.
* 11.0: 11 0.
* 10.2.1: 10 2 1.
* 10.2: 10 2.
* 10.1: 10 1.
* 10.0.1: 10 0 1.
* 10.0: 10 0.
* 9.1: 9 1.
* 9.0.1: 9 0 1.
* 9.0: 9 0.
* 8.4: 8 4.
* 8.3: 8 3.
* 8.2.1: 8 2 1.
* 8.2: 8 2.
* 8.1: 8 1.
* 8.0.4: 8 0 4.
* 8.0.3: 8 0 3.
* 8.0.2: 8 0 2.
* 8.0.1: 8 0 1.
* 8.0: 8 0.
* 7.0: 7 0.
* 6.1: 6 1.
* 6.0.2: 6 0 2.
* 6.0.1: 6 0 1.
* 6.0: 6 0.
* 5.8: 5 8.
* 5.7: 5 7.
* 5.6: 5 6.
* 5.5.1: 5 5 1.
* 5.5: 5 5.
* 5.4.2: 5 4 2.
* 5.4.1: 5 4 1.
* 5.4: 5 4.
* 5.3: 5 3.
* 5.2: 5 2.
* 5.1: 5 1.
* 5.0.2: 5 0 2.
* 5.0.1: 5 0 1.
* 5.0: 5 0.
* 3.7.1 and 3.8.1 and 4.0.1: 3 7 1 and 3 8 1 and 4 0 1.
* 4.0: 4 0.
* 3.8: 3 8.
* 3.7: 3 7.
* 3.6: 3 6.
* 3.5.2: 3 5 2.
* 3.5.1: 3 5 1.
* 3.5: 3 5.
* 3.4.4: 3 4 4.
* 3.4.3: 3 4 3.
* 3.4.2: 3 4 2.
* 3.4.1: 3 4 1.
* 3.4: 3 4.
* 3.3: 3 3.
* 3.2: 3 2.
* 3.1: 3 1.
* 3.0.2: 3 0 2.
* 3.0.1: 3 0 1.
* 3.0: 3 0.
* 2.2: 2 2.
* 2.1.2: 2 1 2.
* 2.1.1: 2 1 1.
* 2.1: 2 1.
* 2.0.2: 2 0 2.
* 2.0.1: 2 0 1.
* 2.0: 2 0.
* 1.4.2: 1 4 2.
* 1.4.1: 1 4 1.
* 1.4: 1 4.
* 1.3.2: 1 3 2.
* 1.3.1: 1 3 1.
* 1.3: 1 3.
* 1.2: 1 2.
* 1.1.7: 1 1 7.
* 1.1.6: 1 1 6.
* 1.1.5: 1 1 5.
* 1.1.4: 1 1 4.
* 1.1.3: 1 1 3.
* 1.1.2: 1 1 2.
* 1.1.1: 1 1 1.
* 1.1: 1 1.
* 1.0: 1 0.
* 0.9.8: 0 9 8.
* 0.9.7: 0 9 7.
* 0.9.6: 0 9 6.
* 0.9.5: 0 9 5.
* 0.9.4: 0 9 4.
* 0.9.3: 0 9 3.
* 0.9.2: 0 9 2.
* 0.9.1: 0 9 1.
* 0.9: 0 9.
* 0.8: 0 8.
* 0.7.8: 0 7 8.
* 0.7.7: 0 7 7.
* 0.7.6: 0 7 6.
* 0.7.5: 0 7 5.
* 0.7.4: 0 7 4.
* 0.7.3: 0 7 3.
* 0.7.2: 0 7 2.
* 0.7.1: 0 7 1.
* 0.7: 0 7.
* 0.7b4: 0 7b4.
* 0.6.49: 0 6 49.
* 0.6.48: 0 6 48.
* 0.6.47: 0 6 47.
* 0.6.46: 0 6 46.
* 0.6.45: 0 6 45.
* 0.6.44: 0 6 44.
* 0.6.43: 0 6 43.
* 0.6.42: 0 6 42.
* 0.6.41: 0 6 41.
* 0.6.40: 0 6 40.
* 0.6.39: 0 6 39.
* 0.6.38: 0 6 38.
* 0.6.37: 0 6 37.
* 0.6.36: 0 6 36.
* 0.6.35: 0 6 35.
* 0.6.34: 0 6 34.
* 0.6.33: 0 6 33.
* 0.6.32: 0 6 32.
* 0.6.31: 0 6 31.
* 0.6.30: 0 6 30.
* 0.6.29: 0 6 29.
* 0.6.28: 0 6 28.
* 0.6.27: 0 6 27.
* 0.6.26: 0 6 26.
* 0.6.25: 0 6 25.
* 0.6.24: 0 6 24.
* 0.6.23: 0 6 23.
* 0.6.21: 0 6 21.
* 0.6.20: 0 6 20.
* 0.6.19: 0 6 19.
* 0.6.18: 0 6 18.
* 0.6.17: 0 6 17.
* 0.6.16: 0 6 16.
* 0.6.15: 0 6 15.
* 0.6.14: 0 6 14.
* 0.6.13: 0 6 13.
* 0.6.12: 0 6 12.
* 0.6.11: 0 6 11.
* 0.6.10: 0 6 10.
* 0.6.9: 0 6 9.
* 0.6.8: 0 6 8.
* 0.6.7: 0 6 7.
* 0.6.6: 0 6 6.
* 0.6.5: 0 6 5.
* 0.6.4: 0 6 4.
* 0.6.3: 0 6 3.
* 0.6.2: 0 6 2.
* 0.6.1: 0 6 1.
* 0.6: 0 6.
* 0.6c9: 0 6c9.
* 0.6c7: 0 6c7.
* 0.6c6: 0 6c6.
* 0.6c5: 0 6c5.
* 0.6c4: 0 6c4.
* 0.6c3: 0 6c3.
* 0.6c2: 0 6c2.
* 0.6c1: 0 6c1.
* 0.6b4: 0 6b4.
* 0.6b3: 0 6b3.
* 0.6b2: 0 6b2.
* 0.6b1: 0 6b1.
* 0.6a11: 0 6a11.
* 0.6a10: 0 6a10.
* 0.6a9: 0 6a9.
* 0.6a8: 0 6a8.
* 0.6a7: 0 6a7.
* 0.6a6: 0 6a6.
* 0.6a5: 0 6a5.
* 0.6a3: 0 6a3.
* 0.6a2: 0 6a2.
* 0.6a1: 0 6a1.
* 0.5a12: 0 5a12.
* 0.5a11: 0 5a11.
* 0.5a10: 0 5a10.
* 0.5a9: 0 5a9.
* 0.5a8: 0 5a8.
* 0.5a7: 0 5a7.
* 0.5a6: 0 5a6.
* 0.5a5: 0 5a5.
* 0.5a4: 0 5a4.
* 0.5a3: 0 5a3.
* 0.5a2: 0 5a2.
* 0.5a1: 0 5a1.
* 0.4a4: 0 4a4.
* 0.4a3: 0 4a3.
* 0.4a2: 0 4a2.
* 0.4a1: 0 4a1.
* 0.3a4: 0 3a4.
* 0.3a3: 0 3a3.
* 0.3a2: 0 3a2.
* 0.3a1: 0 3a1.


File: setuptools.info,  Node: v50 3 2,  Next: v50 3 1,  Up: History<2>

9.1 v50.3.2
===========

17 Oct 2020

* Menu:

* Documentation changes::
* Misc::


File: setuptools.info,  Node: Documentation changes,  Next: Misc,  Up: v50 3 2

9.1.1 Documentation changes
---------------------------

   * #2394(1): Extended towncrier news template to include change note
     categories.  This allows to see what types of changes a given
     version introduces – by @webknjaz(2)

   * #2427(3): Started enforcing strict syntax and reference validation
     in the Sphinx docs – by @webknjaz(4)

   * #2428(5): Removed redundant Sphinx ‘Makefile’ support – by
     @webknjaz(6)

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/2394

   (2) https://github.com/sponsors/webknjaz

   (3) https://github.com/pypa/setuptools/issues/2427

   (4) https://github.com/sponsors/webknjaz

   (5) https://github.com/pypa/setuptools/issues/2428

   (6) https://github.com/sponsors/webknjaz


File: setuptools.info,  Node: Misc,  Prev: Documentation changes,  Up: v50 3 2

9.1.2 Misc
----------

   * #2401(1): Enabled test results reporting in AppVeyor CI – by
     @webknjaz(2)

   * #2420(3): Replace Python 3.9.0 beta with 3.9.0 final on GitHub
     Actions.

   * #2421(4): Python 3.9 Trove classifier got added to the dist
     metadata – by @webknjaz(5)

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/2401

   (2) https://github.com/sponsors/webknjaz

   (3) https://github.com/pypa/setuptools/issues/2420

   (4) https://github.com/pypa/setuptools/issues/2421

   (5) https://github.com/sponsors/webknjaz


File: setuptools.info,  Node: v50 3 1,  Next: v50 3 0,  Prev: v50 3 2,  Up: History<2>

9.2 v50.3.1
===========

14 Oct 2020

* Menu:

* Documentation changes: Documentation changes<2>.
* Misc: Misc<2>.


File: setuptools.info,  Node: Documentation changes<2>,  Next: Misc<2>,  Up: v50 3 1

9.2.1 Documentation changes
---------------------------

   * #2093(1): Finalized doc revamp.

   * #2097(2): doc: simplify index and group deprecated files

   * #2102(3): doc overhaul step 2: break main doc into multiple
     sections

   * #2111(4): doc overhaul step 3: update userguide

   * #2395(5): Added a ‘:user:’ role to Sphinx config – by @webknjaz(6)

   * #2395(7): Added an illustrative explanation about the change notes
     to fragments dir – by @webknjaz(8)

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/2093

   (2) https://github.com/pypa/setuptools/issues/2097

   (3) https://github.com/pypa/setuptools/issues/2102

   (4) https://github.com/pypa/setuptools/issues/2111

   (5) https://github.com/pypa/setuptools/issues/2395

   (6) https://github.com/sponsors/webknjaz

   (7) https://github.com/pypa/setuptools/issues/2395

   (8) https://github.com/sponsors/webknjaz


File: setuptools.info,  Node: Misc<2>,  Prev: Documentation changes<2>,  Up: v50 3 1

9.2.2 Misc
----------

   * #2379(1): Travis CI test suite now tests against PPC64.

   * #2413(2): Suppress EOF errors (and other exceptions) when importing
     lib2to3.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/2379

   (2) https://github.com/pypa/setuptools/issues/2413


File: setuptools.info,  Node: v50 3 0,  Next: v50 2 0,  Prev: v50 3 1,  Up: History<2>

9.3 v50.3.0
===========

05 Sep 2020

* Menu:

* Changes::


File: setuptools.info,  Node: Changes,  Up: v50 3 0

9.3.1 Changes
-------------

   * #2368(1): In distutils, restore support for monkeypatched
     CCompiler.spawn per pypa/distutils#15(2).

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/2368

   (2) https://github.com/pypa/distutils/issues/15


File: setuptools.info,  Node: v50 2 0,  Next: v50 1 0,  Prev: v50 3 0,  Up: History<2>

9.4 v50.2.0
===========

04 Sep 2020

* Menu:

* Changes: Changes<2>.


File: setuptools.info,  Node: Changes<2>,  Up: v50 2 0

9.4.1 Changes
-------------

   * #2355(1): When pip is imported as part of a build, leave distutils
     patched.

   * #2380(2): There are some setuptools specific changes in the
     ‘setuptools.command.bdist_rpm’ module that are no longer needed,
     because they are part of the ‘bdist_rpm’ module in distutils in
     Python 3.5.0.  Therefore, code was removed from
     ‘setuptools.command.bdist_rpm’.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/2355

   (2) https://github.com/pypa/setuptools/issues/2380


File: setuptools.info,  Node: v50 1 0,  Next: v50 0 3,  Prev: v50 2 0,  Up: History<2>

9.5 v50.1.0
===========

02 Sep 2020

* Menu:

* Changes: Changes<3>.


File: setuptools.info,  Node: Changes<3>,  Up: v50 1 0

9.5.1 Changes
-------------

   * #2350(1): Setuptools reverts using the included distutils by
     default.  Platform maintainers and system integrators and others
     are `strongly' encouraged to set ‘SETUPTOOLS_USE_DISTUTILS=local’
     to help identify and work through the reported issues with
     distutils adoption, mainly to file issues and pull requests with
     pypa/distutils such that distutils performs as needed across every
     supported environment.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/2350


File: setuptools.info,  Node: v50 0 3,  Next: v50 0 2,  Prev: v50 1 0,  Up: History<2>

9.6 v50.0.3
===========

01 Sep 2020

* Menu:

* Misc: Misc<3>.


File: setuptools.info,  Node: Misc<3>,  Up: v50 0 3

9.6.1 Misc
----------

   * #2363(1): Restore link_libpython support on Python 3.7 and earlier
     (see pypa/distutils#9(2)).

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/2363

   (2) https://github.com/pypa/distutils/issues/9


File: setuptools.info,  Node: v50 0 2,  Next: v50 0 1,  Prev: v50 0 3,  Up: History<2>

9.7 v50.0.2
===========

01 Sep 2020

* Menu:

* Misc: Misc<4>.


File: setuptools.info,  Node: Misc<4>,  Up: v50 0 2

9.7.1 Misc
----------

   * #2352(1): In distutils hack, use absolute import rather than
     relative to avoid bpo-30876(2).

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/2352

   (2) http://bugs.python.org/issue30876


File: setuptools.info,  Node: v50 0 1,  Next: v50 0 0,  Prev: v50 0 2,  Up: History<2>

9.8 v50.0.1
===========

01 Sep 2020

* Menu:

* Misc: Misc<5>.


File: setuptools.info,  Node: Misc<5>,  Up: v50 0 1

9.8.1 Misc
----------

   * #2357(1): Restored Python 3.5 support in distutils.util for missing
     ‘subprocess._optim_args_from_interpreter_flags’.

   * #2358(2): Restored AIX support on Python 3.8 and earlier.

   * #2361(3): Add Python 3.10 support to _distutils_hack.  Get the
     ‘Loader’ abstract class from importlib.abc rather than
     importlib.util.abc (alias removed in Python 3.10).

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/2357

   (2) https://github.com/pypa/setuptools/issues/2358

   (3) https://github.com/pypa/setuptools/issues/2361


File: setuptools.info,  Node: v50 0 0,  Next: v49 6 0,  Prev: v50 0 1,  Up: History<2>

9.9 v50.0.0
===========

20 Aug 2020

* Menu:

* Breaking Changes::
* Changes: Changes<4>.


File: setuptools.info,  Node: Breaking Changes,  Next: Changes<4>,  Up: v50 0 0

9.9.1 Breaking Changes
----------------------

   * #2232(1): Once again, Setuptools overrides the stdlib distutils on
     import.  For environments or invocations where this behavior is
     undesirable, users are provided with a temporary escape hatch.  If
     the environment variable ‘SETUPTOOLS_USE_DISTUTILS’ is set to
     ‘stdlib’, Setuptools will fall back to the legacy behavior.  Use of
     this escape hatch is discouraged, but it is provided to ease the
     transition while proper fixes for edge cases can be addressed.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/2232


File: setuptools.info,  Node: Changes<4>,  Prev: Breaking Changes,  Up: v50 0 0

9.9.2 Changes
-------------

   * #2334(1): In MSVC module, refine text in error message.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/2334


File: setuptools.info,  Node: v49 6 0,  Next: v49 5 0,  Prev: v50 0 0,  Up: History<2>

9.10 v49.6.0
============

13 Aug 2020

* Menu:

* Changes: Changes<5>.


File: setuptools.info,  Node: Changes<5>,  Up: v49 6 0

9.10.1 Changes
--------------

   * #2129(1): In pkg_resources, no longer detect any pathname ending in
     .egg as a Python egg.  Now the path must be an unpacked egg or a
     zip file.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/2129


File: setuptools.info,  Node: v49 5 0,  Next: v49 4 0,  Prev: v49 6 0,  Up: History<2>

9.11 v49.5.0
============

13 Aug 2020

* Menu:

* Changes: Changes<6>.


File: setuptools.info,  Node: Changes<6>,  Up: v49 5 0

9.11.1 Changes
--------------

   * #2306(1): When running as a PEP 517(2) backend, setuptools does not
     try to install ‘setup_requires’ itself.  They are reported as build
     requirements for the frontend to install.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/2306

   (2) https://www.python.org/dev/peps/pep-0517/


File: setuptools.info,  Node: v49 4 0,  Next: v49 3 2,  Prev: v49 5 0,  Up: History<2>

9.12 v49.4.0
============

13 Aug 2020

* Menu:

* Changes: Changes<7>.


File: setuptools.info,  Node: Changes<7>,  Up: v49 4 0

9.12.1 Changes
--------------

   * #2310(1): Updated vendored packaging version to 20.4.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/2310


File: setuptools.info,  Node: v49 3 2,  Next: v49 3 1,  Prev: v49 4 0,  Up: History<2>

9.13 v49.3.2
============

12 Aug 2020

* Menu:

* Documentation changes: Documentation changes<3>.
* Misc: Misc<6>.


File: setuptools.info,  Node: Documentation changes<3>,  Next: Misc<6>,  Up: v49 3 2

9.13.1 Documentation changes
----------------------------

   * #2300(1): Improve the ‘safe_version’ function documentation

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/2300


File: setuptools.info,  Node: Misc<6>,  Prev: Documentation changes<3>,  Up: v49 3 2

9.13.2 Misc
-----------

   * #2297(1): Once again, in stubs prefer exec_module to the deprecated
     load_module.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/2297


File: setuptools.info,  Node: v49 3 1,  Next: v49 3 0,  Prev: v49 3 2,  Up: History<2>

9.14 v49.3.1
============

10 Aug 2020

* Menu:

* Changes: Changes<8>.


File: setuptools.info,  Node: Changes<8>,  Up: v49 3 1

9.14.1 Changes
--------------

   * #2316(1): Removed warning when ‘distutils’ is imported before
     ‘setuptools’ when ‘distutils’ replacement is not enabled.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/2316


File: setuptools.info,  Node: v49 3 0,  Next: v49 2 1,  Prev: v49 3 1,  Up: History<2>

9.15 v49.3.0
============

09 Aug 2020

* Menu:

* Changes: Changes<9>.


File: setuptools.info,  Node: Changes<9>,  Up: v49 3 0

9.15.1 Changes
--------------

   * #2259(1): Setuptools now provides a .pth file (except for editable
     installs of setuptools) to the target environment to ensure that
     when enabled, the setuptools-provided distutils is preferred before
     setuptools has been imported (and even if setuptools is never
     imported).  Honors the SETUPTOOLS_USE_DISTUTILS environment
     variable.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/2259


File: setuptools.info,  Node: v49 2 1,  Next: v49 2 0,  Prev: v49 3 0,  Up: History<2>

9.16 v49.2.1
============

02 Aug 2020

* Menu:

* Misc: Misc<7>.


File: setuptools.info,  Node: Misc<7>,  Up: v49 2 1

9.16.1 Misc
-----------

   * #2257(1): Fixed two flaws in
     distutils._msvccompiler.MSVCCompiler.spawn.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/2257


File: setuptools.info,  Node: v49 2 0,  Next: v49 1 3,  Prev: v49 2 1,  Up: History<2>

9.17 v49.2.0
============

12 Jul 2020

* Menu:

* Changes: Changes<10>.


File: setuptools.info,  Node: Changes<10>,  Up: v49 2 0

9.17.1 Changes
--------------

   * #2230(1): Now warn the user when setuptools is imported after
     distutils modules have been loaded (exempting PyPy for 3.6),
     directing the users of packages to import setuptools first.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/2230


File: setuptools.info,  Node: v49 1 3,  Next: v49 1 2,  Prev: v49 2 0,  Up: History<2>

9.18 v49.1.3
============

12 Jul 2020

* Menu:

* Misc: Misc<8>.


File: setuptools.info,  Node: Misc<8>,  Up: v49 1 3

9.18.1 Misc
-----------

   * #2212(1): (Distutils) Allow spawn to accept environment.  Avoid
     monkey-patching global state.

   * #2249(2): Fix extension loading technique in stubs.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/2212

   (2) https://github.com/pypa/setuptools/issues/2249


File: setuptools.info,  Node: v49 1 2,  Next: v49 1 1,  Prev: v49 1 3,  Up: History<2>

9.19 v49.1.2
============

11 Jul 2020

* Menu:

* Changes: Changes<11>.


File: setuptools.info,  Node: Changes<11>,  Up: v49 1 2

9.19.1 Changes
--------------

   * #2232(1): In preparation for re-enabling a local copy of distutils,
     Setuptools now honors an environment variable,
     SETUPTOOLS_USE_DISTUTILS. If set to ‘stdlib’ (current default),
     distutils will be used from the standard library.  If set to
     ‘local’ (default in a imminent backward-incompatible release), the
     local copy of distutils will be used.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/2232


File: setuptools.info,  Node: v49 1 1,  Next: v49 0 1,  Prev: v49 1 2,  Up: History<2>

9.20 v49.1.1
============

10 Jul 2020

* Menu:

* Misc: Misc<9>.


File: setuptools.info,  Node: Misc<9>,  Up: v49 1 1

9.20.1 Misc
-----------

   * #2094(1): Removed pkg_resources.py2_warn module, which is no longer
     reachable.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/2094


File: setuptools.info,  Node: v49 0 1,  Next: v49 1 0,  Prev: v49 1 1,  Up: History<2>

9.21 v49.0.1
============

05 Jul 2020

* Menu:

* Misc: Misc<10>.


File: setuptools.info,  Node: Misc<10>,  Up: v49 0 1

9.21.1 Misc
-----------

   * #2228(1): Applied fix for pypa/distutils#3(2), restoring
     expectation that spawn will raise a DistutilsExecError when
     attempting to execute a missing file.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/2228

   (2) https://github.com/pypa/distutils/issues/3


File: setuptools.info,  Node: v49 1 0,  Next: v49 0 0,  Prev: v49 0 1,  Up: History<2>

9.22 v49.1.0
============

03 Jul 2020

* Menu:

* Changes: Changes<12>.


File: setuptools.info,  Node: Changes<12>,  Up: v49 1 0

9.22.1 Changes
--------------

   * #2228(1): Disabled distutils adoption for now while emergent issues
     are addressed.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/2228


File: setuptools.info,  Node: v49 0 0,  Next: v48 0 0,  Prev: v49 1 0,  Up: History<2>

9.23 v49.0.0
============

03 Jul 2020

* Menu:

* Breaking Changes: Breaking Changes<2>.
* Changes: Changes<13>.
* Misc: Misc<11>.


File: setuptools.info,  Node: Breaking Changes<2>,  Next: Changes<13>,  Up: v49 0 0

9.23.1 Breaking Changes
-----------------------

   * #2165(1): Setuptools no longer installs a site.py file during
     easy_install or develop installs.  As a result, .eggs on PYTHONPATH
     will no longer take precedence over other packages on sys.path.  If
     this issue affects your production environment, please reach out to
     the maintainers at #2165(2).

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/2165

   (2) https://github.com/pypa/setuptools/issues/2165


File: setuptools.info,  Node: Changes<13>,  Next: Misc<11>,  Prev: Breaking Changes<2>,  Up: v49 0 0

9.23.2 Changes
--------------

   * #2137(1): Removed (private) pkg_resources.RequirementParseError,
     now replaced by packaging.requirements.InvalidRequirement.  Kept
     the name for compatibility, but users should catch
     InvalidRequirement instead.

   * #2180(2): Update vendored packaging in pkg_resources to 19.2.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/2137

   (2) https://github.com/pypa/setuptools/issues/2180


File: setuptools.info,  Node: Misc<11>,  Prev: Changes<13>,  Up: v49 0 0

9.23.3 Misc
-----------

   * #2199(1): Fix exception causes all over the codebase by using
     ‘raise new_exception from old_exception’

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/2199


File: setuptools.info,  Node: v48 0 0,  Next: v47 3 2,  Prev: v49 0 0,  Up: History<2>

9.24 v48.0.0
============

03 Jul 2020

* Menu:

* Breaking Changes: Breaking Changes<3>.


File: setuptools.info,  Node: Breaking Changes<3>,  Up: v48 0 0

9.24.1 Breaking Changes
-----------------------

   * #2143(1): Setuptools adopts distutils from the Python 3.9 standard
     library and no longer depends on distutils in the standard library.
     When importing ‘setuptools’ or ‘setuptools.distutils_patch’,
     Setuptools will expose its bundled version as a top-level
     ‘distutils’ package (and unload any previously-imported top-level
     distutils package), retaining the expectation that ‘distutils’’
     objects are actually Setuptools objects.  To avoid getting any
     legacy behavior from the standard library, projects are advised to
     always “import setuptools” prior to importing anything from
     distutils.  This behavior happens by default when using ‘pip
     install’ or ‘pep517.build’.  Workflows that rely on ‘setup.py
     (anything)’ will need to first ensure setuptools is imported.  One
     way to achieve this behavior without modifying code is to invoke
     Python thus: ‘python -c "import setuptools;
     exec(open('setup.py').read())" (anything)’.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/2143


File: setuptools.info,  Node: v47 3 2,  Next: v47 3 1,  Prev: v48 0 0,  Up: History<2>

9.25 v47.3.2
============

03 Jul 2020

* Menu:

* Misc: Misc<12>.


File: setuptools.info,  Node: Misc<12>,  Up: v47 3 2

9.25.1 Misc
-----------

   * #2071(1): Replaced references to the deprecated imp package with
     references to importlib

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/2071


File: setuptools.info,  Node: v47 3 1,  Next: v47 3 0,  Prev: v47 3 2,  Up: History<2>

9.26 v47.3.1
============

16 Jun 2020

* Menu:

* Misc: Misc<13>.


File: setuptools.info,  Node: Misc<13>,  Up: v47 3 1

9.26.1 Misc
-----------

   * #1973(1): Removed ‘pkg_resources.py31compat.makedirs’ in favor of
     the stdlib.  Use ‘os.makedirs()’ instead.

   * #2198(2): Restore ‘__requires__’ directive in easy-install wrapper
     scripts.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1973

   (2) https://github.com/pypa/setuptools/issues/2198


File: setuptools.info,  Node: v47 3 0,  Next: v47 2 0,  Prev: v47 3 1,  Up: History<2>

9.27 v47.3.0
============

15 Jun 2020

* Menu:

* Changes: Changes<14>.
* Misc: Misc<14>.


File: setuptools.info,  Node: Changes<14>,  Next: Misc<14>,  Up: v47 3 0

9.27.1 Changes
--------------

   * #2197(1): Console script wrapper for editable installs now has a
     unified template and honors importlib_metadata if present for
     faster script execution on older Pythons.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/2197


File: setuptools.info,  Node: Misc<14>,  Prev: Changes<14>,  Up: v47 3 0

9.27.2 Misc
-----------

   * #2195(1): Fix broken entry points generated by easy-install (pip
     editable installs).

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/2195


File: setuptools.info,  Node: v47 2 0,  Next: v47 1 1,  Prev: v47 3 0,  Up: History<2>

9.28 v47.2.0
============

15 Jun 2020

* Menu:

* Changes: Changes<15>.


File: setuptools.info,  Node: Changes<15>,  Up: v47 2 0

9.28.1 Changes
--------------

   * #2194(1): Editable-installed entry points now load significantly
     faster on Python versions 3.8+.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/2194


File: setuptools.info,  Node: v47 1 1,  Next: v44 1 1,  Prev: v47 2 0,  Up: History<2>

9.29 v47.1.1
============

28 May 2020

* Menu:

* Documentation changes: Documentation changes<4>.
* Incorporate changes from v44.1.1;: Incorporate changes from v44 1 1.


File: setuptools.info,  Node: Documentation changes<4>,  Next: Incorporate changes from v44 1 1,  Up: v47 1 1

9.29.1 Documentation changes
----------------------------

   * #2156(1): Update mailing list pointer in developer docs

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/2156


File: setuptools.info,  Node: Incorporate changes from v44 1 1,  Prev: Documentation changes<4>,  Up: v47 1 1

9.29.2 Incorporate changes from v44.1.1:
----------------------------------------

   * #2158(1): Avoid loading working set during
     ‘Distribution.finalize_options’ prior to invoking
     ‘_install_setup_requires’, broken since v42.0.0.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/2158


File: setuptools.info,  Node: v44 1 1,  Next: v47 1 0,  Prev: v47 1 1,  Up: History<2>

9.30 v44.1.1
============

28 May 2020

* Menu:

* Misc: Misc<15>.


File: setuptools.info,  Node: Misc<15>,  Up: v44 1 1

9.30.1 Misc
-----------

   * #2158(1): Avoid loading working set during
     ‘Distribution.finalize_options’ prior to invoking
     ‘_install_setup_requires’, broken since v42.0.0.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/2158


File: setuptools.info,  Node: v47 1 0,  Next: v47 0 0,  Prev: v44 1 1,  Up: History<2>

9.31 v47.1.0
============

28 May 2020

* Menu:

* Changes: Changes<16>.


File: setuptools.info,  Node: Changes<16>,  Up: v47 1 0

9.31.1 Changes
--------------

   * #2070(1): In wheel-to-egg conversion, use simple
     pkg_resources-style namespace declaration for packages that declare
     namespace_packages.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/2070


File: setuptools.info,  Node: v47 0 0,  Next: v46 4 0,  Prev: v47 1 0,  Up: History<2>

9.32 v47.0.0
============

28 May 2020

* Menu:

* Breaking Changes: Breaking Changes<4>.
* Changes: Changes<17>.


File: setuptools.info,  Node: Breaking Changes<4>,  Next: Changes<17>,  Up: v47 0 0

9.32.1 Breaking Changes
-----------------------

   * #2094(1): Setuptools now actively crashes under Python 2.  Python
     3.5 or later is required.  Users of Python 2 should use
     ‘setuptools<45’.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/2094


File: setuptools.info,  Node: Changes<17>,  Prev: Breaking Changes<4>,  Up: v47 0 0

9.32.2 Changes
--------------

   * #1700(1): Document all supported keywords by migrating the ones
     from distutils.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1700


File: setuptools.info,  Node: v46 4 0,  Next: v46 3 1,  Prev: v47 0 0,  Up: History<2>

9.33 v46.4.0
============

16 May 2020

* Menu:

* Changes: Changes<18>.


File: setuptools.info,  Node: Changes<18>,  Up: v46 4 0

9.33.1 Changes
--------------

   * #1753(1): ‘attr:’ now extracts variables through rudimentary
     examination of the AST, thereby supporting modules with third-party
     imports.  If examining the AST fails to find the variable, ‘attr:’
     falls back to the old behavior of importing the module.  Works on
     Python 3 only.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1753


File: setuptools.info,  Node: v46 3 1,  Next: v46 3 0,  Prev: v46 4 0,  Up: History<2>

9.34 v46.3.1
============

15 May 2020

No significant changes.


File: setuptools.info,  Node: v46 3 0,  Next: v46 2 0,  Prev: v46 3 1,  Up: History<2>

9.35 v46.3.0
============

13 May 2020

* Menu:

* Changes: Changes<19>.
* Misc: Misc<16>.


File: setuptools.info,  Node: Changes<19>,  Next: Misc<16>,  Up: v46 3 0

9.35.1 Changes
--------------

   * #2089(1): Package index functionality no longer attempts to remove
     an md5 fragment from the index URL. This functionality, added for
     distribute #163(2) is no longer relevant.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/2089

   (2) https://github.com/pypa/setuptools/issues/163


File: setuptools.info,  Node: Misc<16>,  Prev: Changes<19>,  Up: v46 3 0

9.35.2 Misc
-----------

   * #2041(1): Preserve file modes during pkg files copying, but clear
     read only flag for target afterwards.

   * #2105(2): Filter ‘2to3’ deprecation warnings from
     ‘TestDevelop.test_2to3_user_mode’.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/2041

   (2) https://github.com/pypa/setuptools/issues/2105


File: setuptools.info,  Node: v46 2 0,  Next: v46 1 3,  Prev: v46 3 0,  Up: History<2>

9.36 v46.2.0
============

10 May 2020

* Menu:

* Changes: Changes<20>.
* Documentation changes: Documentation changes<5>.
* Misc: Misc<17>.


File: setuptools.info,  Node: Changes<20>,  Next: Documentation changes<5>,  Up: v46 2 0

9.36.1 Changes
--------------

   * #2040(1): Deprecated the ‘bdist_wininst’ command.  Binary packages
     should be built as wheels instead.

   * #2062(2): Change ‘Mac OS X’ to ‘macOS’ in code.

   * #2075(3): Stop recognizing files ending with ‘.dist-info’ as
     distribution metadata.

   * #2086(4): Deprecate ‘use_2to3’ functionality.  Packagers are
     encouraged to use single-source solutions or build tool chains to
     manage conversions outside of setuptools.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/2040

   (2) https://github.com/pypa/setuptools/issues/2062

   (3) https://github.com/pypa/setuptools/issues/2075

   (4) https://github.com/pypa/setuptools/issues/2086


File: setuptools.info,  Node: Documentation changes<5>,  Next: Misc<17>,  Prev: Changes<20>,  Up: v46 2 0

9.36.2 Documentation changes
----------------------------

   * #1698(1): Added documentation for ‘build_meta’ (a bare minimum, not
     completed).

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1698


File: setuptools.info,  Node: Misc<17>,  Prev: Documentation changes<5>,  Up: v46 2 0

9.36.3 Misc
-----------

   * #2082(1): Filter ‘lib2to3’ ‘PendingDeprecationWarning’ and
     ‘DeprecationWarning’ in tests, because ‘lib2to3’ is deprecated in
     Python 3.9(2).

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/2082

   (2) https://bugs.python.org/issue40360


File: setuptools.info,  Node: v46 1 3,  Next: v46 1 2,  Prev: v46 2 0,  Up: History<2>

9.37 v46.1.3
============

25 Mar 2020

No significant changes.


File: setuptools.info,  Node: v46 1 2,  Next: v46 1 1,  Prev: v46 1 3,  Up: History<2>

9.38 v46.1.2
============

25 Mar 2020

* Menu:

* Misc: Misc<18>.


File: setuptools.info,  Node: Misc<18>,  Up: v46 1 2

9.38.1 Misc
-----------

   * #1458(1): Added template for reporting Python 2 incompatibilities.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1458


File: setuptools.info,  Node: v46 1 1,  Next: v46 1 0,  Prev: v46 1 2,  Up: History<2>

9.39 v46.1.1
============

21 Mar 2020

No significant changes.


File: setuptools.info,  Node: v46 1 0,  Next: v44 1 0,  Prev: v46 1 1,  Up: History<2>

9.40 v46.1.0
============

21 Mar 2020

* Menu:

* Changes: Changes<21>.
* Incorporate changes from v44.1.0;: Incorporate changes from v44 1 0.


File: setuptools.info,  Node: Changes<21>,  Next: Incorporate changes from v44 1 0,  Up: v46 1 0

9.40.1 Changes
--------------

   * #308(1): Allow version number normalization to be bypassed by
     wrapping in a ‘setuptools.sic()’ call.

   * #1424(2): Prevent keeping files mode for package_data build.  It
     may break a build if user’s package data has read only flag.

   * #1431(3): In ‘easy_install.check_site_dir’, ensure the installation
     directory exists.

   * #1563(4): In ‘pkg_resources’ prefer ‘find_spec’ (PEP 451(5)) to
     ‘find_module’.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/308

   (2) https://github.com/pypa/setuptools/issues/1424

   (3) https://github.com/pypa/setuptools/issues/1431

   (4) https://github.com/pypa/setuptools/issues/1563

   (5) https://www.python.org/dev/peps/pep-0451/


File: setuptools.info,  Node: Incorporate changes from v44 1 0,  Prev: Changes<21>,  Up: v46 1 0

9.40.2 Incorporate changes from v44.1.0:
----------------------------------------

   * #1704(1): Set sys.argv[0] in setup script run by
     build_meta.__legacy__

   * #1959(2): Fix for Python 4: replace unsafe six.PY3 with six.PY2

   * #1994(3): Fixed a bug in the
     “setuptools.finalize_distribution_options” hook that lead to
     ignoring the order attribute of entry points managed by this hook.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1704

   (2) https://github.com/pypa/setuptools/issues/1959

   (3) https://github.com/pypa/setuptools/issues/1994


File: setuptools.info,  Node: v44 1 0,  Next: v46 0 0,  Prev: v46 1 0,  Up: History<2>

9.41 v44.1.0
============

21 Mar 2020

* Menu:

* Changes: Changes<22>.


File: setuptools.info,  Node: Changes<22>,  Up: v44 1 0

9.41.1 Changes
--------------

   * #1704(1): Set sys.argv[0] in setup script run by
     build_meta.__legacy__

   * #1959(2): Fix for Python 4: replace unsafe six.PY3 with six.PY2

   * #1994(3): Fixed a bug in the
     “setuptools.finalize_distribution_options” hook that lead to
     ignoring the order attribute of entry points managed by this hook.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1704

   (2) https://github.com/pypa/setuptools/issues/1959

   (3) https://github.com/pypa/setuptools/issues/1994


File: setuptools.info,  Node: v46 0 0,  Next: v45 3 0,  Prev: v44 1 0,  Up: History<2>

9.42 v46.0.0
============

08 Mar 2020

* Menu:

* Breaking Changes: Breaking Changes<5>.
* Changes: Changes<23>.
* Documentation changes: Documentation changes<6>.
* Misc: Misc<19>.


File: setuptools.info,  Node: Breaking Changes<5>,  Next: Changes<23>,  Up: v46 0 0

9.42.1 Breaking Changes
-----------------------

   * #65(1): Once again as in 3.0, removed the Features feature.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/65


File: setuptools.info,  Node: Changes<23>,  Next: Documentation changes<6>,  Prev: Breaking Changes<5>,  Up: v46 0 0

9.42.2 Changes
--------------

   * #1890(1): Fix vendored dependencies so importing
     ‘setuptools.extern.some_module’ gives the same object as
     ‘setuptools._vendor.some_module’.  This makes Metadata picklable
     again.

   * #1899(2): Test suite now fails on warnings.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1890

   (2) https://github.com/pypa/setuptools/issues/1899


File: setuptools.info,  Node: Documentation changes<6>,  Next: Misc<19>,  Prev: Changes<23>,  Up: v46 0 0

9.42.3 Documentation changes
----------------------------

   * #2011(1): Fix broken link to distutils docs on package_data

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/2011


File: setuptools.info,  Node: Misc<19>,  Prev: Documentation changes<6>,  Up: v46 0 0

9.42.4 Misc
-----------

   * #1991(1): Include pkg_resources test data in sdist, so tests can be
     executed from it.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1991


File: setuptools.info,  Node: v45 3 0,  Next: v45 2 0,  Prev: v46 0 0,  Up: History<2>

9.43 v45.3.0
============

07 Mar 2020

* Menu:

* Changes: Changes<24>.


File: setuptools.info,  Node: Changes<24>,  Up: v45 3 0

9.43.1 Changes
--------------

   * #1557(1): Deprecated eggsecutable scripts and updated docs.

   * #1904(2): Update msvc.py to use CPython 3.8.0 mechanism to find
     msvc 14+

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1557

   (2) https://github.com/pypa/setuptools/issues/1904


File: setuptools.info,  Node: v45 2 0,  Next: v45 1 0,  Prev: v45 3 0,  Up: History<2>

9.44 v45.2.0
============

08 Feb 2020

* Menu:

* Changes: Changes<25>.
* Misc: Misc<20>.


File: setuptools.info,  Node: Changes<25>,  Next: Misc<20>,  Up: v45 2 0

9.44.1 Changes
--------------

   * #1905(1): Fixed defect in _imp, introduced in 41.6.0 when the
     ‘tests’ directory is not present.

   * #1941(2): Improve editable installs with PEP 518(3) build
     isolation:

        * The ‘--user’ option is now always available.  A warning is
          issued if the user site directory is not available.

        * The error shown when the install directory is not in
          ‘PYTHONPATH’ has been turned into a warning.

   * #1981(4): Setuptools now declares its ‘tests’ and ‘docs’
     dependencies in metadata (extras).

   * #1985(5): Add support for installing scripts in environments where
     bdist_wininst is missing (i.e.  Python 3.9).

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1905

   (2) https://github.com/pypa/setuptools/issues/1941

   (3) https://www.python.org/dev/peps/pep-0518/

   (4) https://github.com/pypa/setuptools/issues/1981

   (5) https://github.com/pypa/setuptools/issues/1985


File: setuptools.info,  Node: Misc<20>,  Prev: Changes<25>,  Up: v45 2 0

9.44.2 Misc
-----------

   * #1968(1): Add flake8-2020 to check for misuse of sys.version or
     sys.version_info.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1968


File: setuptools.info,  Node: v45 1 0,  Next: v45 0 0,  Prev: v45 2 0,  Up: History<2>

9.45 v45.1.0
============

19 Jan 2020

* Menu:

* Changes: Changes<26>.


File: setuptools.info,  Node: Changes<26>,  Up: v45 1 0

9.45.1 Changes
--------------

   * #1458(1): Add minimum sunset date and preamble to Python 2 warning.

   * #1704(2): Set sys.argv[0] in setup script run by
     build_meta.__legacy__

   * #1974(3): Add Python 3 Only Trove Classifier and remove universal
     wheel declaration for more complete transition from Python 2.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1458

   (2) https://github.com/pypa/setuptools/issues/1704

   (3) https://github.com/pypa/setuptools/issues/1974


File: setuptools.info,  Node: v45 0 0,  Next: v44 0 0,  Prev: v45 1 0,  Up: History<2>

9.46 v45.0.0
============

11 Jan 2020

* Menu:

* Breaking Changes: Breaking Changes<6>.
* Changes: Changes<27>.


File: setuptools.info,  Node: Breaking Changes<6>,  Next: Changes<27>,  Up: v45 0 0

9.46.1 Breaking Changes
-----------------------

   * #1458(1): Drop support for Python 2.  Setuptools now requires
     Python 3.5 or later.  Install setuptools using pip >=9 or pin to
     Setuptools <45 to maintain 2.7 support.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1458


File: setuptools.info,  Node: Changes<27>,  Prev: Breaking Changes<6>,  Up: v45 0 0

9.46.2 Changes
--------------

   * #1959(1): Fix for Python 4: replace unsafe six.PY3 with six.PY2

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1959


File: setuptools.info,  Node: v44 0 0,  Next: v43 0 0,  Prev: v45 0 0,  Up: History<2>

9.47 v44.0.0
============

01 Jan 2020

* Menu:

* Breaking Changes: Breaking Changes<7>.


File: setuptools.info,  Node: Breaking Changes<7>,  Up: v44 0 0

9.47.1 Breaking Changes
-----------------------

   * #1908(1): Drop support for Python 3.4.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1908


File: setuptools.info,  Node: v43 0 0,  Next: v42 0 2,  Prev: v44 0 0,  Up: History<2>

9.48 v43.0.0
============

31 Dec 2019

* Menu:

* Breaking Changes: Breaking Changes<8>.
* Changes: Changes<28>.


File: setuptools.info,  Node: Breaking Changes<8>,  Next: Changes<28>,  Up: v43 0 0

9.48.1 Breaking Changes
-----------------------

   * #1634(1): Include ‘pyproject.toml’ in source distribution by
     default.  Projects relying on the previous behavior where
     ‘pyproject.toml’ was excluded by default should stop relying on
     that behavior or add ‘exclude pyproject.toml’ to their MANIFEST.in
     file.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1634


File: setuptools.info,  Node: Changes<28>,  Prev: Breaking Changes<8>,  Up: v43 0 0

9.48.2 Changes
--------------

   * #1927(1): Setuptools once again declares ‘setuptools’ in the
     ‘build-system.requires’ and adds PEP 517(2) build support by
     declaring itself as the ‘build-backend’.  It additionally specifies
     ‘build-system.backend-path’ to rely on itself for those builders
     that support it.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1927

   (2) https://www.python.org/dev/peps/pep-0517/


File: setuptools.info,  Node: v42 0 2,  Next: v42 0 1,  Prev: v43 0 0,  Up: History<2>

9.49 v42.0.2
============

01 Dec 2019

* Menu:

* Changes: Changes<29>.


File: setuptools.info,  Node: Changes<29>,  Up: v42 0 2

9.49.1 Changes
--------------

   * #1921(1): Fix support for easy_install’s ‘find-links’ option in
     ‘setup.cfg’.

   * #1922(2): Build dependencies (setup_requires and tests_require) now
     install transitive dependencies indicated by extras.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1921

   (2) https://github.com/pypa/setuptools/issues/1922


File: setuptools.info,  Node: v42 0 1,  Next: v42 0 0,  Prev: v42 0 2,  Up: History<2>

9.50 v42.0.1
============

25 Nov 2019

* Menu:

* Changes: Changes<30>.


File: setuptools.info,  Node: Changes<30>,  Up: v42 0 1

9.50.1 Changes
--------------

   * #1918(1): Fix regression in handling wheels compatibility tags.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1918


File: setuptools.info,  Node: v42 0 0,  Next: v41 6 0,  Prev: v42 0 1,  Up: History<2>

9.51 v42.0.0
============

23 Nov 2019

* Menu:

* Breaking Changes: Breaking Changes<9>.
* Changes: Changes<31>.


File: setuptools.info,  Node: Breaking Changes<9>,  Next: Changes<31>,  Up: v42 0 0

9.51.1 Breaking Changes
-----------------------

   * 
     #1830(1), #1909(2): Mark the easy_install script and setuptools command as deprecated, and use pip(3) when available to fetch/build wheels for missing ‘setup_requires’/‘tests_require’ requirements, with the following differences in behavior:

             * support for ‘python_requires’

             * better support for wheels (proper handling of priority
               with respect to PEP 425(4) tags)

             * PEP 517(5)/518 support

             * eggs are not supported

             * no support for the ‘allow_hosts’ easy_install option
               (‘index_url’/‘find_links’ are still honored)

             * pip environment variables are honored (and take
               precedence over easy_install options)

   * #1898(6): Removed the “upload” and “register” commands in favor of
     twine(7).

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1830

   (2) https://github.com/pypa/setuptools/issues/1909

   (3) https://pip.pypa.io/en/stable/

   (4) https://www.python.org/dev/peps/pep-0425/

   (5) https://www.python.org/dev/peps/pep-0517/

   (6) https://github.com/pypa/setuptools/issues/1898

   (7) https://pypi.org/p/twine


File: setuptools.info,  Node: Changes<31>,  Prev: Breaking Changes<9>,  Up: v42 0 0

9.51.2 Changes
--------------

   * #1767(1): Add support for the ‘license_files’ option in ‘setup.cfg’
     to automatically include multiple license files in a source
     distribution.

   * #1829(2): Update handling of wheels compatibility tags: * add
     support for manylinux2010 * fix use of removed ‘m’ ABI flag in
     Python 3.8 on Windows

   * #1861(3): Fix empty namespace package installation from wheel.

   * #1877(4): Setuptools now exposes a new entry point hook
     “setuptools.finalize_distribution_options”, enabling plugins like
     setuptools_scm(5) to configure options on the distribution at
     finalization time.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1767

   (2) https://github.com/pypa/setuptools/issues/1829

   (3) https://github.com/pypa/setuptools/issues/1861

   (4) https://github.com/pypa/setuptools/issues/1877

   (5) https://pypi.org/project/setuptools_scm


File: setuptools.info,  Node: v41 6 0,  Next: v41 5 1,  Prev: v42 0 0,  Up: History<2>

9.52 v41.6.0
============

29 Oct 2019

* Menu:

* Changes: Changes<32>.


File: setuptools.info,  Node: Changes<32>,  Up: v41 6 0

9.52.1 Changes
--------------

   * #479(1): Replace usage of deprecated ‘imp’ module with local
     re-implementation in ‘setuptools._imp’.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/479


File: setuptools.info,  Node: v41 5 1,  Next: v41 5 0,  Prev: v41 6 0,  Up: History<2>

9.53 v41.5.1
============

28 Oct 2019

* Menu:

* Changes: Changes<33>.


File: setuptools.info,  Node: Changes<33>,  Up: v41 5 1

9.53.1 Changes
--------------

   * #1891(1): Fix code for detecting Visual Studio’s version on Windows
     under Python 2.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1891


File: setuptools.info,  Node: v41 5 0,  Next: v41 4 0,  Prev: v41 5 1,  Up: History<2>

9.54 v41.5.0
============

27 Oct 2019

* Menu:

* Changes: Changes<34>.
* Documentation changes: Documentation changes<7>.
* Misc: Misc<21>.


File: setuptools.info,  Node: Changes<34>,  Next: Documentation changes<7>,  Up: v41 5 0

9.54.1 Changes
--------------

   * #1811(1): Improve Visual C++ 14.X support, mainly for Visual Studio
     2017 and 2019.

   * #1814(2): Fix ‘pkg_resources.Requirement’ hash/equality
     implementation: take PEP 508(3) direct URL into account.

   * #1824(4): Fix tests when running under ‘python3.10’.

   * #1878(5): Formally deprecated the ‘test’ command, with the
     recommendation that users migrate to ‘tox’.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1811

   (2) https://github.com/pypa/setuptools/issues/1814

   (3) https://www.python.org/dev/peps/pep-0508/

   (4) https://github.com/pypa/setuptools/issues/1824

   (5) https://github.com/pypa/setuptools/issues/1878


File: setuptools.info,  Node: Documentation changes<7>,  Next: Misc<21>,  Prev: Changes<34>,  Up: v41 5 0

9.54.2 Documentation changes
----------------------------

   * #1860(1): Update documentation to mention the egg format is not
     supported by pip and dependency links support was dropped starting
     with pip 19.0.

   * #1862(2): Drop ez_setup documentation: deprecated for some time
     (last updated in 2016), and still relying on easy_install
     (deprecated too).

   * #1868(3): Drop most documentation references to (deprecated)
     EasyInstall.

   * #1884(4): Added a trove classifier to document support for Python
     3.8.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1860

   (2) https://github.com/pypa/setuptools/issues/1862

   (3) https://github.com/pypa/setuptools/issues/1868

   (4) https://github.com/pypa/setuptools/issues/1884


File: setuptools.info,  Node: Misc<21>,  Prev: Documentation changes<7>,  Up: v41 5 0

9.54.3 Misc
-----------

   * #1886(1): Added Python 3.8 release to the Travis test matrix.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1886


File: setuptools.info,  Node: v41 4 0,  Next: v41 3 0,  Prev: v41 5 0,  Up: History<2>

9.55 v41.4.0
============

06 Oct 2019

* Menu:

* Changes: Changes<35>.


File: setuptools.info,  Node: Changes<35>,  Up: v41 4 0

9.55.1 Changes
--------------

   * #1847(1): In declarative config, now traps errors when invalid
     ‘python_requires’ values are supplied.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1847


File: setuptools.info,  Node: v41 3 0,  Next: v41 2 0,  Prev: v41 4 0,  Up: History<2>

9.56 v41.3.0
============

06 Oct 2019

* Menu:

* Changes: Changes<36>.
* Misc: Misc<22>.


File: setuptools.info,  Node: Changes<36>,  Next: Misc<22>,  Up: v41 3 0

9.56.1 Changes
--------------

   * #1690(1): When storing extras, rely on OrderedSet to retain order
     of extras as indicated by the packager, which will also be
     deterministic on Python 2.7 (with PYTHONHASHSEED unset) and Python
     3.6+.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1690


File: setuptools.info,  Node: Misc<22>,  Prev: Changes<36>,  Up: v41 3 0

9.56.2 Misc
-----------

   * #1858(1): Fixed failing integration test triggered by
     ‘long_description_content_type’ in packaging.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1858


File: setuptools.info,  Node: v41 2 0,  Next: v41 1 0,  Prev: v41 3 0,  Up: History<2>

9.57 v41.2.0
============

21 Aug 2019

* Menu:

* Changes: Changes<37>.
* Misc: Misc<23>.


File: setuptools.info,  Node: Changes<37>,  Next: Misc<23>,  Up: v41 2 0

9.57.1 Changes
--------------

   * #479(1): Remove some usage of the deprecated ‘imp’ module.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/479


File: setuptools.info,  Node: Misc<23>,  Prev: Changes<37>,  Up: v41 2 0

9.57.2 Misc
-----------

   * #1565(1): Changed html_sidebars from string to list of string as
     per ‘https://www.sphinx-doc.org/en/master/changes.html#id58’

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1565


File: setuptools.info,  Node: v41 1 0,  Next: v41 0 1,  Prev: v41 2 0,  Up: History<2>

9.58 v41.1.0
============

13 Aug 2019

* Menu:

* Misc: Misc<24>.
* Documentation changes: Documentation changes<8>.


File: setuptools.info,  Node: Misc<24>,  Next: Documentation changes<8>,  Up: v41 1 0

9.58.1 Misc
-----------

   * #1697(1): Moved most of the constants from setup.py to setup.cfg

   * #1749(2): Fixed issue with the PEP 517(3) backend where building a
     source distribution would fail if any tarball existed in the
     destination directory.

   * #1750(4): Fixed an issue with PEP 517(5) backend where wheel builds
     would fail if the destination directory did not already exist.

   * #1756(6): Force metadata-version >= 1.2.  when project urls are
     present.

   * #1769(7): Improve ‘package_data’ check: ensure the dictionary
     values are lists/tuples of strings.

   * #1788(8): Changed compatibility fallback logic for ‘html.unescape’
     to avoid accessing ‘HTMLParser.unescape’ when not necessary.
     ‘HTMLParser.unescape’ is deprecated and will be removed in Python
     3.9.

   * #1790(9): Added the file path to the error message when a
     ‘UnicodeDecodeError’ occurs while reading a metadata file.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1697

   (2) https://github.com/pypa/setuptools/issues/1749

   (3) https://www.python.org/dev/peps/pep-0517/

   (4) https://github.com/pypa/setuptools/issues/1750

   (5) https://www.python.org/dev/peps/pep-0517/

   (6) https://github.com/pypa/setuptools/issues/1756

   (7) https://github.com/pypa/setuptools/issues/1769

   (8) https://github.com/pypa/setuptools/issues/1788

   (9) https://github.com/pypa/setuptools/issues/1790


File: setuptools.info,  Node: Documentation changes<8>,  Prev: Misc<24>,  Up: v41 1 0

9.58.2 Documentation changes
----------------------------

   * #1776(1): Use license classifiers rather than the license field.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1776


File: setuptools.info,  Node: v41 0 1,  Next: v41 0 0,  Prev: v41 1 0,  Up: History<2>

9.59 v41.0.1
============

22 Apr 2019

* Menu:

* Changes: Changes<38>.


File: setuptools.info,  Node: Changes<38>,  Up: v41 0 1

9.59.1 Changes
--------------

   * #1671(1): Fixed issue with the PEP 517(2) backend that prevented
     building a wheel when the ‘dist/’ directory contained existing
     ‘.whl’ files.

   * #1709(3): In test.paths_on_python_path, avoid adding unnecessary
     duplicates to the PYTHONPATH.

   * #1741(4): In package_index, now honor “current directory” during a
     checkout of git and hg repositories under Windows

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1671

   (2) https://www.python.org/dev/peps/pep-0517/

   (3) https://github.com/pypa/setuptools/issues/1709

   (4) https://github.com/pypa/setuptools/issues/1741


File: setuptools.info,  Node: v41 0 0,  Next: v40 9 0,  Prev: v41 0 1,  Up: History<2>

9.60 v41.0.0
============

05 Apr 2019

* Menu:

* Breaking Changes: Breaking Changes<10>.


File: setuptools.info,  Node: Breaking Changes<10>,  Up: v41 0 0

9.60.1 Breaking Changes
-----------------------

   * #1735(1): When parsing setup.cfg files, setuptools now requires the
     files to be encoded as UTF-8.  Any other encoding will lead to a
     UnicodeDecodeError.  This change removes support for specifying an
     encoding using a ‘coding: ‘ directive in the header of the file, a
     feature that was introduces in 40.7.  Given the recent release of
     the aforementioned feature, it is assumed that few if any projects
     are utilizing the feature to specify an encoding other than UTF-8.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1735


File: setuptools.info,  Node: v40 9 0,  Next: v40 8 0,  Prev: v41 0 0,  Up: History<2>

9.61 v40.9.0
============

03 Apr 2019

* Menu:

* Changes: Changes<39>.
* Documentation changes: Documentation changes<9>.


File: setuptools.info,  Node: Changes<39>,  Next: Documentation changes<9>,  Up: v40 9 0

9.61.1 Changes
--------------

   * #1675(1): Added support for ‘setup.cfg’-only projects when using
     the ‘setuptools.build_meta’ backend.  Projects that have enabled
     PEP 517(2) no longer need to have a ‘setup.py’ and can use the
     purely declarative ‘setup.cfg’ configuration file instead.

   * #1720(3): Added support for
     ‘pkg_resources.parse_requirements’-style requirements in
     ‘setup_requires’ when ‘setup.py’ is invoked from the
     ‘setuptools.build_meta’ build backend.

   * #1664(4): Added the path to the ‘PKG-INFO’ or ‘METADATA’ file in
     the exception text when the ‘Version:’ header can’t be found.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1675

   (2) https://www.python.org/dev/peps/pep-0517/

   (3) https://github.com/pypa/setuptools/issues/1720

   (4) https://github.com/pypa/setuptools/issues/1664


File: setuptools.info,  Node: Documentation changes<9>,  Prev: Changes<39>,  Up: v40 9 0

9.61.2 Documentation changes
----------------------------

   * #1705(1): Removed some placeholder documentation sections referring
     to deprecated features.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1705


File: setuptools.info,  Node: v40 8 0,  Next: v40 7 3,  Prev: v40 9 0,  Up: History<2>

9.62 v40.8.0
============

05 Feb 2019

* Menu:

* Changes: Changes<40>.


File: setuptools.info,  Node: Changes<40>,  Up: v40 8 0

9.62.1 Changes
--------------

   * #1652(1): Added the ‘build_meta:__legacy__’ backend, a
     “compatibility mode” PEP 517(2) backend that can be used as the
     default when ‘build-backend’ is left unspecified in
     ‘pyproject.toml’.

   * #1635(3): Resource paths are passed to
     ‘pkg_resources.resource_string’ and similar no longer accept paths
     that traverse parents, that begin with a leading ‘/’.  Violations
     of this expectation raise DeprecationWarnings and will become
     errors.  Additionally, any paths that are absolute on Windows are
     strictly disallowed and will raise ValueErrors.

   * #1536(4): ‘setuptools’ will now automatically include licenses if
     ‘setup.cfg’ contains a ‘license_file’ attribute, unless this file
     is manually excluded inside ‘MANIFEST.in’.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1652

   (2) https://www.python.org/dev/peps/pep-0517/

   (3) https://github.com/pypa/setuptools/issues/1635

   (4) https://github.com/pypa/setuptools/issues/1536


File: setuptools.info,  Node: v40 7 3,  Next: v40 7 2,  Prev: v40 8 0,  Up: History<2>

9.63 v40.7.3
============

03 Feb 2019

* Menu:

* Changes: Changes<41>.


File: setuptools.info,  Node: Changes<41>,  Up: v40 7 3

9.63.1 Changes
--------------

   * #1670(1): In package_index, revert to using a copy of splituser
     from Python 3.8.  Attempts to use ‘urllib.parse.urlparse’ led to
     problems as reported in #1663(2) and #1668(3).  This change serves
     as an alternative to #1499(4) and fixes #1668(5).

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1670

   (2) https://github.com/pypa/setuptools/issues/1663

   (3) https://github.com/pypa/setuptools/issues/1668

   (4) https://github.com/pypa/setuptools/issues/1499

   (5) https://github.com/pypa/setuptools/issues/1668


File: setuptools.info,  Node: v40 7 2,  Next: v40 7 1,  Prev: v40 7 3,  Up: History<2>

9.64 v40.7.2
============

31 Jan 2019

* Menu:

* Changes: Changes<42>.


File: setuptools.info,  Node: Changes<42>,  Up: v40 7 2

9.64.1 Changes
--------------

   * #1666(1): Restore port in URL handling in package_index.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1666


File: setuptools.info,  Node: v40 7 1,  Next: v40 7 0,  Prev: v40 7 2,  Up: History<2>

9.65 v40.7.1
============

28 Jan 2019

* Menu:

* Changes: Changes<43>.


File: setuptools.info,  Node: Changes<43>,  Up: v40 7 1

9.65.1 Changes
--------------

   * #1660(1): On Python 2, when reading config files, downcast options
     from text to bytes to satisfy distutils expectations.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1660


File: setuptools.info,  Node: v40 7 0,  Next: v40 6 3,  Prev: v40 7 1,  Up: History<2>

9.66 v40.7.0
============

27 Jan 2019

* Menu:

* Breaking Changes: Breaking Changes<11>.
* Changes: Changes<44>.


File: setuptools.info,  Node: Breaking Changes<11>,  Next: Changes<44>,  Up: v40 7 0

9.66.1 Breaking Changes
-----------------------

   * #1551(1): File inputs for the ‘license’ field in ‘setup.cfg’ files
     now explicitly raise an error.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1551


File: setuptools.info,  Node: Changes<44>,  Prev: Breaking Changes<11>,  Up: v40 7 0

9.66.2 Changes
--------------

   * #1180(1): Add support for non-ASCII in setup.cfg (#1062(2)).  Add
     support for native strings on some parameters (#1136(3)).

   * #1499(4): ‘setuptools.package_index’ no longer relies on the
     deprecated ‘urllib.parse.splituser’ per Python #27485(5).

   * #1544(6): Added tests for PackageIndex.download (for git URLs).

   * #1625(7): In PEP 517(8) build_meta builder, ensure that sdists are
     built as gztar per the spec.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1180

   (2) https://github.com/pypa/setuptools/issues/1062

   (3) https://github.com/pypa/setuptools/issues/1136

   (4) https://github.com/pypa/setuptools/issues/1499

   (5) http://bugs.python.org/issue27485

   (6) https://github.com/pypa/setuptools/issues/1544

   (7) https://github.com/pypa/setuptools/issues/1625

   (8) https://www.python.org/dev/peps/pep-0517/


File: setuptools.info,  Node: v40 6 3,  Next: v40 6 2,  Prev: v40 7 0,  Up: History<2>

9.67 v40.6.3
============

11 Dec 2018

* Menu:

* Changes: Changes<45>.


File: setuptools.info,  Node: Changes<45>,  Up: v40 6 3

9.67.1 Changes
--------------

   * #1594(1): PEP 517(2) backend no longer declares setuptools as a
     dependency as it can be assumed.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1594

   (2) https://www.python.org/dev/peps/pep-0517/


File: setuptools.info,  Node: v40 6 2,  Next: v40 6 1,  Prev: v40 6 3,  Up: History<2>

9.68 v40.6.2
============

13 Nov 2018

* Menu:

* Changes: Changes<46>.


File: setuptools.info,  Node: Changes<46>,  Up: v40 6 2

9.68.1 Changes
--------------

   * #1592(1): Fix invalid dependency on external six module (instead of
     vendored version).

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1592


File: setuptools.info,  Node: v40 6 1,  Next: v40 6 0,  Prev: v40 6 2,  Up: History<2>

9.69 v40.6.1
============

12 Nov 2018

* Menu:

* Changes: Changes<47>.


File: setuptools.info,  Node: Changes<47>,  Up: v40 6 1

9.69.1 Changes
--------------

   * #1590(1): Fixed regression where packages without ‘author’ or
     ‘author_email’ fields generated malformed package metadata.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1590


File: setuptools.info,  Node: v40 6 0,  Next: v40 5 0,  Prev: v40 6 1,  Up: History<2>

9.70 v40.6.0
============

12 Nov 2018

* Menu:

* Deprecations::
* Changes: Changes<48>.
* Documentation changes: Documentation changes<10>.
* Misc: Misc<25>.


File: setuptools.info,  Node: Deprecations,  Next: Changes<48>,  Up: v40 6 0

9.70.1 Deprecations
-------------------

   * #1541(1): Officially deprecated the ‘requires’ parameter in
     ‘setup()’.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1541


File: setuptools.info,  Node: Changes<48>,  Next: Documentation changes<10>,  Prev: Deprecations,  Up: v40 6 0

9.70.2 Changes
--------------

   * #1519(1): In ‘pkg_resources.normalize_path’, additional path
     normalization is now performed to ensure path values to a directory
     is always the same, preventing false positives when checking
     scripts have a consistent prefix to set up on Windows.

   * #1545(2): Changed the warning class of all deprecation warnings;
     deprecation warning classes are no longer derived from
     ‘DeprecationWarning’ and are thus visible by default.

   * #1554(3): ‘build_meta.build_sdist’ now includes ‘setup.py’ in
     source distributions by default.

   * #1576(4): Started monkey-patching ‘get_metadata_version’ and
     ‘read_pkg_file’ onto ‘distutils.DistributionMetadata’ to retain the
     correct version on the ‘PKG-INFO’ file in the (deprecated) ‘upload’
     command.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1519

   (2) https://github.com/pypa/setuptools/issues/1545

   (3) https://github.com/pypa/setuptools/issues/1554

   (4) https://github.com/pypa/setuptools/issues/1576


File: setuptools.info,  Node: Documentation changes<10>,  Next: Misc<25>,  Prev: Changes<48>,  Up: v40 6 0

9.70.3 Documentation changes
----------------------------

   * #1395(1): Changed Pyrex references to Cython in the documentation.

   * #1456(2): Documented that the ‘rpmbuild’ packages is required for
     the ‘bdist_rpm’ command.

   * #1537(3): Documented how to use ‘setup.cfg’ for ‘src/ layouts’

   * #1539(4): Added minimum version column in ‘setup.cfg’ metadata
     table.

   * #1552(5): Fixed a minor typo in the python 2/3 compatibility
     documentation.

   * #1553(6): Updated installation instructions to point to ‘pip
     install’ instead of ‘ez_setup.py’.

   * #1560(7): Updated ‘setuptools’ distribution documentation to remove
     some outdated information.

   * #1564(8): Documented ‘setup.cfg’ minimum version for version and
     project_urls.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1395

   (2) https://github.com/pypa/setuptools/issues/1456

   (3) https://github.com/pypa/setuptools/issues/1537

   (4) https://github.com/pypa/setuptools/issues/1539

   (5) https://github.com/pypa/setuptools/issues/1552

   (6) https://github.com/pypa/setuptools/issues/1553

   (7) https://github.com/pypa/setuptools/issues/1560

   (8) https://github.com/pypa/setuptools/issues/1564


File: setuptools.info,  Node: Misc<25>,  Prev: Documentation changes<10>,  Up: v40 6 0

9.70.4 Misc
-----------

   * #1533(1): Restricted the ‘recursive-include setuptools/_vendor’ to
     contain only .py and .txt files.

   * #1572(2): Added the ‘concurrent.futures’ backport ‘futures’ to the
     Python 2.7 test suite requirements.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1533

   (2) https://github.com/pypa/setuptools/issues/1572


File: setuptools.info,  Node: v40 5 0,  Next: v40 4 3,  Prev: v40 6 0,  Up: History<2>

9.71 v40.5.0
============

26 Oct 2018

* Menu:

* Changes: Changes<49>.
* Documentation changes: Documentation changes<11>.


File: setuptools.info,  Node: Changes<49>,  Next: Documentation changes<11>,  Up: v40 5 0

9.71.1 Changes
--------------

   * #1335(1): In ‘pkg_resources.normalize_path’, fix issue on Cygwin
     when cwd contains symlinks.

   * #1502(2): Deprecated support for downloads from Subversion in
     package_index/easy_install.

   * #1517(3): Dropped use of six.u in favor of ‘u""’ literals.

   * #1520(4): Added support for ‘data_files’ in ‘setup.cfg’.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1335

   (2) https://github.com/pypa/setuptools/issues/1502

   (3) https://github.com/pypa/setuptools/issues/1517

   (4) https://github.com/pypa/setuptools/issues/1520


File: setuptools.info,  Node: Documentation changes<11>,  Prev: Changes<49>,  Up: v40 5 0

9.71.2 Documentation changes
----------------------------

   * #1525(1): Fixed rendering of the deprecation warning in
     easy_install doc.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1525


File: setuptools.info,  Node: v40 4 3,  Next: v40 4 2,  Prev: v40 5 0,  Up: History<2>

9.72 v40.4.3
============

23 Sep 2018

* Menu:

* Changes: Changes<50>.


File: setuptools.info,  Node: Changes<50>,  Up: v40 4 3

9.72.1 Changes
--------------

   * #1480(1): Bump vendored pyparsing in pkg_resources to 2.2.1.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1480


File: setuptools.info,  Node: v40 4 2,  Next: v40 4 1,  Prev: v40 4 3,  Up: History<2>

9.73 v40.4.2
============

21 Sep 2018

* Menu:

* Misc: Misc<26>.


File: setuptools.info,  Node: Misc<26>,  Up: v40 4 2

9.73.1 Misc
-----------

   * #1497(1): Updated gitignore in repo.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1497


File: setuptools.info,  Node: v40 4 1,  Next: v40 4 0,  Prev: v40 4 2,  Up: History<2>

9.74 v40.4.1
============

18 Sep 2018

* Menu:

* Changes: Changes<51>.


File: setuptools.info,  Node: Changes<51>,  Up: v40 4 1

9.74.1 Changes
--------------

   * #1480(1): Bump vendored pyparsing to 2.2.1.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1480


File: setuptools.info,  Node: v40 4 0,  Next: v40 3 0,  Prev: v40 4 1,  Up: History<2>

9.75 v40.4.0
============

18 Sep 2018

* Menu:

* Changes: Changes<52>.


File: setuptools.info,  Node: Changes<52>,  Up: v40 4 0

9.75.1 Changes
--------------

   * #1481(1): Join the sdist ‘--dist-dir’ and the ‘build_meta’ sdist
     directory argument to point to the same target (meaning the build
     frontend no longer needs to clean manually the dist dir to avoid
     multiple sdist presence, and setuptools no longer needs to handle
     conflicts between the two).

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1481


File: setuptools.info,  Node: v40 3 0,  Next: v40 2 0,  Prev: v40 4 0,  Up: History<2>

9.76 v40.3.0
============

16 Sep 2018

* Menu:

* Changes: Changes<53>.
* Misc: Misc<27>.


File: setuptools.info,  Node: Changes<53>,  Next: Misc<27>,  Up: v40 3 0

9.76.1 Changes
--------------

   * #1402(1): Fixed a bug with namespace packages under Python 3.6 when
     one package in current directory hides another which is installed.

   * #1427(2): Set timestamp of ‘.egg-info’ directory whenever
     ‘egg_info’ command is run.

   * #1474(3): ‘build_meta.get_requires_for_build_sdist’ now does not
     include the ‘wheel’ package anymore.

   * #1486(4): Suppress warnings in pkg_resources.handle_ns.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1402

   (2) https://github.com/pypa/setuptools/issues/1427

   (3) https://github.com/pypa/setuptools/issues/1474

   (4) https://github.com/pypa/setuptools/issues/1486


File: setuptools.info,  Node: Misc<27>,  Prev: Changes<53>,  Up: v40 3 0

9.76.2 Misc
-----------

   * #1479(1): Remove internal use of six.binary_type.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1479


File: setuptools.info,  Node: v40 2 0,  Next: v40 1 1,  Prev: v40 3 0,  Up: History<2>

9.77 v40.2.0
============

21 Aug 2018

* Menu:

* Changes: Changes<54>.


File: setuptools.info,  Node: Changes<54>,  Up: v40 2 0

9.77.1 Changes
--------------

   * #1466(1): Fix handling of Unicode arguments in PEP 517(2) backend

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1466

   (2) https://www.python.org/dev/peps/pep-0517/


File: setuptools.info,  Node: v40 1 1,  Next: v40 1 0,  Prev: v40 2 0,  Up: History<2>

9.78 v40.1.1
============

21 Aug 2018

* Menu:

* Changes: Changes<55>.


File: setuptools.info,  Node: Changes<55>,  Up: v40 1 1

9.78.1 Changes
--------------

   * #1465(1): Fix regression with ‘egg_info’ command when tagging is
     used.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1465


File: setuptools.info,  Node: v40 1 0,  Next: v40 0 0,  Prev: v40 1 1,  Up: History<2>

9.79 v40.1.0
============

17 Aug 2018

* Menu:

* Changes: Changes<56>.
* Misc: Misc<28>.


File: setuptools.info,  Node: Changes<56>,  Next: Misc<28>,  Up: v40 1 0

9.79.1 Changes
--------------

   * #1410(1): Deprecated ‘upload’ and ‘register’ commands.

   * #1312(2): Introduced find_namespace_packages() to find PEP 420(3)
     namespace packages.

   * #1420(4): Added find_namespace: directive to config parser.

   * #1418(5): Solved race in when creating egg cache directories.

   * #1450(6): Upgraded vendored PyParsing from 2.1.10 to 2.2.0.

   * #1451(7): Upgraded vendored appdirs from 1.4.0 to 1.4.3.

   * #1388(8): Fixed “Microsoft Visual C++ Build Tools” link in
     exception when Visual C++ not found.

   * #1389(9): Added support for scripts which have unicode content.

   * #1416(10): Moved several Python version checks over to using
     ‘six.PY2’ and ‘six.PY3’.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1410

   (2) https://github.com/pypa/setuptools/issues/1312

   (3) https://www.python.org/dev/peps/pep-0420/

   (4) https://github.com/pypa/setuptools/issues/1420

   (5) https://github.com/pypa/setuptools/issues/1418

   (6) https://github.com/pypa/setuptools/issues/1450

   (7) https://github.com/pypa/setuptools/issues/1451

   (8) https://github.com/pypa/setuptools/issues/1388

   (9) https://github.com/pypa/setuptools/issues/1389

   (10) https://github.com/pypa/setuptools/issues/1416


File: setuptools.info,  Node: Misc<28>,  Prev: Changes<56>,  Up: v40 1 0

9.79.2 Misc
-----------

   * #1441(1): Removed spurious executable permissions from files that
     don’t need them.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1441


File: setuptools.info,  Node: v40 0 0,  Next: v39 2 0,  Prev: v40 1 0,  Up: History<2>

9.80 v40.0.0
============

09 Jul 2018

* Menu:

* Breaking Changes: Breaking Changes<12>.
* Changes: Changes<57>.
* Documentation changes: Documentation changes<12>.
* Misc: Misc<29>.


File: setuptools.info,  Node: Breaking Changes<12>,  Next: Changes<57>,  Up: v40 0 0

9.80.1 Breaking Changes
-----------------------

   * #1342(1): Drop support for Python 3.3.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1342


File: setuptools.info,  Node: Changes<57>,  Next: Documentation changes<12>,  Prev: Breaking Changes<12>,  Up: v40 0 0

9.80.2 Changes
--------------

   * #1366(1): In package_index, fixed handling of encoded entities in
     URLs.

   * #1383(2): In pkg_resources VendorImporter, avoid removing packages
     imported from the root.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1366

   (2) https://github.com/pypa/setuptools/issues/1383


File: setuptools.info,  Node: Documentation changes<12>,  Next: Misc<29>,  Prev: Changes<57>,  Up: v40 0 0

9.80.3 Documentation changes
----------------------------

   * #1379(1): Minor doc fixes after actually using the new release
     process.

   * #1385(2): Removed section on non-package data files.

   * #1403(3): Fix developer’s guide.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1379

   (2) https://github.com/pypa/setuptools/issues/1385

   (3) https://github.com/pypa/setuptools/issues/1403


File: setuptools.info,  Node: Misc<29>,  Prev: Documentation changes<12>,  Up: v40 0 0

9.80.4 Misc
-----------

   * #1404(1): Fix PEP 518(2) configuration: set build requirements in
     ‘pyproject.toml’ to ‘["wheel"]’.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1404

   (2) https://www.python.org/dev/peps/pep-0518/


File: setuptools.info,  Node: v39 2 0,  Next: v39 1 0,  Prev: v40 0 0,  Up: History<2>

9.81 v39.2.0
============

19 May 2018

* Menu:

* Changes: Changes<58>.
* Documentation changes: Documentation changes<13>.
* Misc: Misc<30>.


File: setuptools.info,  Node: Changes<58>,  Next: Documentation changes<13>,  Up: v39 2 0

9.81.1 Changes
--------------

   * #1359(1): Support using “file:” to load a PEP 440(2)-compliant
     package version from a text file.

   * #1360(3): Fixed issue with a mismatch between the name of the
     package and the name of the .dist-info file in wheel files

   * #1364(4): Add ‘__dir__()’ implementation to
     ‘pkg_resources.Distribution()’ that includes the attributes in the
     ‘_provider’ instance variable.

   * #1365(5): Take the package_dir option into account when loading the
     version from a module attribute.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1359

   (2) https://www.python.org/dev/peps/pep-0440/

   (3) https://github.com/pypa/setuptools/issues/1360

   (4) https://github.com/pypa/setuptools/issues/1364

   (5) https://github.com/pypa/setuptools/issues/1365


File: setuptools.info,  Node: Documentation changes<13>,  Next: Misc<30>,  Prev: Changes<58>,  Up: v39 2 0

9.81.2 Documentation changes
----------------------------

   * #1353(1): Added coverage badge to README.

   * #1356(2): Made small fixes to the developer guide documentation.

   * #1357(3): Fixed warnings in documentation builds and started
     enforcing that the docs build without warnings in tox.

   * #1376(4): Updated release process docs.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1353

   (2) https://github.com/pypa/setuptools/issues/1356

   (3) https://github.com/pypa/setuptools/issues/1357

   (4) https://github.com/pypa/setuptools/issues/1376


File: setuptools.info,  Node: Misc<30>,  Prev: Documentation changes<13>,  Up: v39 2 0

9.81.3 Misc
-----------

   * #1343(1): The ‘setuptools’ specific
     ‘long_description_content_type’, ‘project_urls’ and
     ‘provides_extras’ fields are now set consistently after any
     ‘distutils’ ‘setup_keywords’ calls, allowing them to override
     values.

   * #1352(2): Added ‘tox’ environment for documentation builds.

   * #1354(3): Added ‘towncrier’ for changelog management.

   * #1355(4): Add PR template.

   * #1368(5): Fixed tests which failed without network connectivity.

   * #1369(6): Added unit tests for PEP 425(7) compatibility tags
     support.

   * #1372(8): Stop testing Python 3.3 in Travis CI, now that the latest
     version of ‘wheel’ no longer installs on it.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1343

   (2) https://github.com/pypa/setuptools/issues/1352

   (3) https://github.com/pypa/setuptools/issues/1354

   (4) https://github.com/pypa/setuptools/issues/1355

   (5) https://github.com/pypa/setuptools/issues/1368

   (6) https://github.com/pypa/setuptools/issues/1369

   (7) https://www.python.org/dev/peps/pep-0425/

   (8) https://github.com/pypa/setuptools/issues/1372


File: setuptools.info,  Node: v39 1 0,  Next: v39 0 1,  Prev: v39 2 0,  Up: History<2>

9.82 v39.1.0
============

28 Apr 2018

   * #1340(1): Update all PyPI URLs to reflect the switch to the new
     Warehouse codebase.

   * #1337(2): In ‘pkg_resources’, now support loading resources for
     modules loaded by the ‘SourcelessFileLoader’.

   * #1332(3): Silence spurious wheel related warnings on Windows.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1340

   (2) https://github.com/pypa/setuptools/issues/1337

   (3) https://github.com/pypa/setuptools/issues/1332


File: setuptools.info,  Node: v39 0 1,  Next: v39 0 0,  Prev: v39 1 0,  Up: History<2>

9.83 v39.0.1
============

18 Mar 2018

   * #1297(1): Restore Unicode handling for Maintainer fields in
     metadata.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1297


File: setuptools.info,  Node: v39 0 0,  Next: v38 7 0,  Prev: v39 0 1,  Up: History<2>

9.84 v39.0.0
============

17 Mar 2018

   * #1296(1): Setuptools now vendors its own direct dependencies, no
     longer relying on the dependencies as vendored by pkg_resources.

   * #296(2): Removed long-deprecated support for iteration on Version
     objects as returned by ‘pkg_resources.parse_version’.  Removed the
     ‘SetuptoolsVersion’ and ‘SetuptoolsLegacyVersion’ names as well.
     They should not have been used, but if they were, replace with
     ‘Version’ and ‘LegacyVersion’ from ‘packaging.version’.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1296

   (2) https://github.com/pypa/setuptools/issues/296


File: setuptools.info,  Node: v38 7 0,  Next: v38 6 1,  Prev: v39 0 0,  Up: History<2>

9.85 v38.7.0
============

17 Mar 2018

   * #1288(1): Add support for maintainer in PKG-INFO.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1288


File: setuptools.info,  Node: v38 6 1,  Next: v38 6 0,  Prev: v38 7 0,  Up: History<2>

9.86 v38.6.1
============

17 Mar 2018

   * #1292(1): Avoid generating ‘Provides-Extra’ in metadata when no
     extra is present (but environment markers are).

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1292


File: setuptools.info,  Node: v38 6 0,  Next: v38 5 2,  Prev: v38 6 1,  Up: History<2>

9.87 v38.6.0
============

15 Mar 2018

   * #1286(1): Add support for Metadata 2.1 (PEP 566(2)).

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1286

   (2) https://www.python.org/dev/peps/pep-0566/


File: setuptools.info,  Node: v38 5 2,  Next: v38 5 1,  Prev: v38 6 0,  Up: History<2>

9.88 v38.5.2
============

06 Mar 2018

   * #1285(1): Fixed RuntimeError in pkg_resources.parse_requirements on
     Python 3.7 (stemming from PEP 479(2)).

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1285

   (2) https://www.python.org/dev/peps/pep-0479/


File: setuptools.info,  Node: v38 5 1,  Next: v38 5 0,  Prev: v38 5 2,  Up: History<2>

9.89 v38.5.1
============

06 Feb 2018

   * #1271(1): Revert to Cython legacy ‘build_ext’ behavior for
     compatibility.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1271


File: setuptools.info,  Node: v38 5 0,  Next: v38 4 1,  Prev: v38 5 1,  Up: History<2>

9.90 v38.5.0
============

04 Feb 2018

   * #1229(1): Expand imports in ‘build_ext’ to refine detection of
     Cython availability.

   * #1270(2): When Cython is available, ‘build_ext’ now uses the
     new_build_ext.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1229

   (2) https://github.com/pypa/setuptools/issues/1270


File: setuptools.info,  Node: v38 4 1,  Next: v38 4 0,  Prev: v38 5 0,  Up: History<2>

9.91 v38.4.1
============

03 Feb 2018

   * #1257(1): In bdist_egg.scan_module, fix ValueError on Python 3.7.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1257


File: setuptools.info,  Node: v38 4 0,  Next: v38 3 0,  Prev: v38 4 1,  Up: History<2>

9.92 v38.4.0
============

05 Jan 2018

   * #1231(1): Removed warning when PYTHONDONTWRITEBYTECODE is enabled.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1231


File: setuptools.info,  Node: v38 3 0,  Next: v38 2 5,  Prev: v38 4 0,  Up: History<2>

9.93 v38.3.0
============

04 Jan 2018

   * #1210(1): Add support for PEP 345(2) Project-URL metadata.

   * #1207(3): Add support for ‘long_description_type’ to setup.cfg
     declarative config as intended and documented.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1210

   (2) https://www.python.org/dev/peps/pep-0345/

   (3) https://github.com/pypa/setuptools/issues/1207


File: setuptools.info,  Node: v38 2 5,  Next: v38 2 4,  Prev: v38 3 0,  Up: History<2>

9.94 v38.2.5
============

   * #1232(1): Fix trailing slash handling in
     ‘pkg_resources.ZipProvider’.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1232


File: setuptools.info,  Node: v38 2 4,  Next: v38 2 3,  Prev: v38 2 5,  Up: History<2>

9.95 v38.2.4
============

04 Dec 2017

   * #1220(1): Fix ‘data_files’ handling when installing from wheel.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1220


File: setuptools.info,  Node: v38 2 3,  Next: v38 2 2,  Prev: v38 2 4,  Up: History<2>

9.96 v38.2.3
============

28 Nov 2017

   * fix Travis’ Python 3.3 job.


File: setuptools.info,  Node: v38 2 2,  Next: v38 2 1,  Prev: v38 2 3,  Up: History<2>

9.97 v38.2.2
============

27 Nov 2017

   * #1214(1): fix handling of namespace packages when installing from a
     wheel.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1214


File: setuptools.info,  Node: v38 2 1,  Next: v38 2 0,  Prev: v38 2 2,  Up: History<2>

9.98 v38.2.1
============

26 Nov 2017

   * #1212(1): fix encoding handling of metadata when installing from a
     wheel.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1212


File: setuptools.info,  Node: v38 2 0,  Next: v38 1 0,  Prev: v38 2 1,  Up: History<2>

9.99 v38.2.0
============

26 Nov 2017

   * #1200(1): easy_install now support installing from wheels: they
     will be installed as standalone unzipped eggs.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1200


File: setuptools.info,  Node: v38 1 0,  Next: v38 0 0,  Prev: v38 2 0,  Up: History<2>

9.100 v38.1.0
=============

25 Nov 2017

   * #1208(1): Improve error message when failing to locate scripts in
     egg-info metadata.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1208


File: setuptools.info,  Node: v38 0 0,  Next: v37 0 0,  Prev: v38 1 0,  Up: History<2>

9.101 v38.0.0
=============

25 Nov 2017

   * #458(1): In order to support deterministic builds, Setuptools no
     longer allows packages to declare ‘install_requires’ as unordered
     sequences (sets or dicts).

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/458


File: setuptools.info,  Node: v37 0 0,  Next: v36 8 0,  Prev: v38 0 0,  Up: History<2>

9.102 v37.0.0
=============

20 Nov 2017

   * #878(1): Drop support for Python 2.6.  Python 2.6 users should rely
     on ‘setuptools < 37dev’.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/878


File: setuptools.info,  Node: v36 8 0,  Next: v36 7 3,  Prev: v37 0 0,  Up: History<2>

9.103 v36.8.0
=============

19 Nov 2017

   * #1190(1): In SSL support for package index operations, use SNI
     where available.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1190


File: setuptools.info,  Node: v36 7 3,  Next: v36 7 2,  Prev: v36 8 0,  Up: History<2>

9.104 v36.7.3
=============

13 Nov 2017

   * #1175(1): Bug fixes to ‘build_meta’ module.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1175


File: setuptools.info,  Node: v36 7 2,  Next: v36 7 1,  Prev: v36 7 3,  Up: History<2>

9.105 v36.7.2
=============

13 Nov 2017

   * #701(1): Fixed duplicate test discovery on Python 3.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/701


File: setuptools.info,  Node: v36 7 1,  Next: v36 7 0,  Prev: v36 7 2,  Up: History<2>

9.106 v36.7.1
=============

11 Nov 2017

   * #1193(1): Avoid test failures in bdist_egg when
     PYTHONDONTWRITEBYTECODE is set.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1193


File: setuptools.info,  Node: v36 7 0,  Next: v36 6 1,  Prev: v36 7 1,  Up: History<2>

9.107 v36.7.0
=============

09 Nov 2017

   * #1054(1): Support ‘setup_requires’ in ‘setup.cfg’ files.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1054


File: setuptools.info,  Node: v36 6 1,  Next: v36 6 0,  Prev: v36 7 0,  Up: History<2>

9.108 v36.6.1
=============

09 Nov 2017

   * #1132(1): Removed redundant and costly serialization/parsing step
     in ‘EntryPoint.__init__’.

   * #844(2): ‘bdist_egg --exclude-source-files’ now tested and works on
     Python 3.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1132

   (2) https://github.com/pypa/setuptools/issues/844


File: setuptools.info,  Node: v36 6 0,  Next: v36 5 0,  Prev: v36 6 1,  Up: History<2>

9.109 v36.6.0
=============

12 Oct 2017

   * #1143(1): Added ‘setuptools.build_meta’ module, an implementation
     of PEP-517(2) for Setuptools-defined packages.

   * #1143(3): Added ‘dist_info’ command for producing dist_info
     metadata.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1143

   (2) https://www.python.org/dev/peps/pep-0517/

   (3) https://github.com/pypa/setuptools/issues/1143


File: setuptools.info,  Node: v36 5 0,  Next: v36 4 0,  Prev: v36 6 0,  Up: History<2>

9.110 v36.5.0
=============

15 Sep 2017

   * #170(1): When working with Mercurial checkouts, use
     Windows-friendly syntax for suppressing output.

   * Inspired by #1134(2), performed substantial refactoring of
     ‘pkg_resources.find_on_path’ to facilitate an optimization for
     paths with many non-version entries.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/170

   (2) https://github.com/pypa/setuptools/issues/1134


File: setuptools.info,  Node: v36 4 0,  Next: v36 3 0,  Prev: v36 5 0,  Up: History<2>

9.111 v36.4.0
=============

03 Sep 2017

   * #1075(1): Add new ‘Description-Content-Type’ metadata field.  See
     here for documentation on how to use this field.(2)

   * #1068(3): Sort files and directories when building eggs for
     deterministic order.

   * #196(4): Remove caching of easy_install command in fetch_build_egg.
     Fixes issue where ‘pytest-runner-N.N’ would satisfy the
     installation of ‘pytest’.

   * #1129(5): Fix working set dependencies handling when replacing
     conflicting distributions (e.g.  when using ‘setup_requires’ with a
     conflicting transitive dependency, fix #1124(6)).

   * #1133(7): Improved handling of README files extensions and added
     Markdown to the list of searched READMES.

   * #1135(8): Improve performance of pkg_resources import by not
     invoking ‘access’ or ‘stat’ and using ‘os.listdir’ instead.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1075

   (2) 
https://packaging.python.org/specifications/#description-content-type

   (3) https://github.com/pypa/setuptools/issues/1068

   (4) https://github.com/pypa/setuptools/issues/196

   (5) https://github.com/pypa/setuptools/issues/1129

   (6) https://github.com/pypa/setuptools/issues/1124

   (7) https://github.com/pypa/setuptools/issues/1133

   (8) https://github.com/pypa/setuptools/issues/1135


File: setuptools.info,  Node: v36 3 0,  Next: v36 2 7,  Prev: v36 4 0,  Up: History<2>

9.112 v36.3.0
=============

28 Aug 2017

   * #1131(1): Make possible using several files within ‘file:’
     directive in metadata.long_description in ‘setup.cfg’.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1131


File: setuptools.info,  Node: v36 2 7,  Next: v36 2 6,  Prev: v36 3 0,  Up: History<2>

9.113 v36.2.7
=============

02 Aug 2017

   * fix #1105(1): Fix handling of requirements with environment markers
     when declared in ‘setup.cfg’ (same treatment as for #1081(2)).

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1105

   (2) https://github.com/pypa/setuptools/issues/1081


File: setuptools.info,  Node: v36 2 6,  Next: v36 2 5,  Prev: v36 2 7,  Up: History<2>

9.114 v36.2.6
=============

31 Jul 2017

   * #462(1): Don’t assume a directory is an egg by the ‘.egg’ extension
     alone.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/462


File: setuptools.info,  Node: v36 2 5,  Next: v36 2 4,  Prev: v36 2 6,  Up: History<2>

9.115 v36.2.5
=============

30 Jul 2017

   * #1093(1): Fix test command handler with extras_require.

   * #1112(2), #1091(3), #1115(4): Now using Trusty containers in Travis
     for CI and CD.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1093

   (2) https://github.com/pypa/setuptools/issues/1112

   (3) https://github.com/pypa/setuptools/issues/1091

   (4) https://github.com/pypa/setuptools/issues/1115


File: setuptools.info,  Node: v36 2 4,  Next: v36 2 3,  Prev: v36 2 5,  Up: History<2>

9.116 v36.2.4
=============

26 Jul 2017

   * #1092(1): ‘pkg_resources’ now uses ‘inspect.getmro’ to resolve
     classes in method resolution order.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1092


File: setuptools.info,  Node: v36 2 3,  Next: v36 2 2,  Prev: v36 2 4,  Up: History<2>

9.117 v36.2.3
=============

25 Jul 2017

   * #1102(1): Restore behavior for empty extras.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1102


File: setuptools.info,  Node: v36 2 2,  Next: v36 2 1,  Prev: v36 2 3,  Up: History<2>

9.118 v36.2.2
=============

24 Jul 2017

   * #1099(1): Revert commit a3ec721, restoring intended purpose of
     extras as part of a requirement declaration.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1099


File: setuptools.info,  Node: v36 2 1,  Next: v36 2 0,  Prev: v36 2 2,  Up: History<2>

9.119 v36.2.1
=============

23 Jul 2017

   * fix #1086(1)

   * fix #1087(2)

   * support extras specifiers in install_requires requirements

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1086

   (2) https://github.com/pypa/setuptools/issues/1087


File: setuptools.info,  Node: v36 2 0,  Next: v36 1 1,  Prev: v36 2 1,  Up: History<2>

9.120 v36.2.0
=============

13 Jul 2017

   * #1081(1): Environment markers indicated in ‘install_requires’ are
     now processed and treated as nameless ‘extras_require’ with
     markers, allowing their metadata in requires.txt to be correctly
     generated.

   * #1053(2): Tagged commits are now released using Travis-CI build
     stages, meaning releases depend on passing tests on all supported
     Python versions (Linux) and not just the latest Python version.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1081

   (2) https://github.com/pypa/setuptools/issues/1053


File: setuptools.info,  Node: v36 1 1,  Next: v36 1 0,  Prev: v36 2 0,  Up: History<2>

9.121 v36.1.1
=============

13 Jul 2017

   * #1083(1): Correct ‘py31compat.makedirs’ to correctly honor
     ‘exist_ok’ parameter.

   * #1083(2): Also use makedirs compatibility throughout setuptools.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1083

   (2) https://github.com/pypa/setuptools/issues/1083


File: setuptools.info,  Node: v36 1 0,  Next: v36 0 1,  Prev: v36 1 1,  Up: History<2>

9.122 v36.1.0
=============

13 Jul 2017

   * #1083(1): Avoid race condition on directory creation in
     ‘pkg_resources.ensure_directory’.

   * Removed deprecation of and restored support for ‘upload_docs’
     command for sites other than PyPI. Only warehouse is dropping
     support, but services like devpi(2) continue to support docs built
     by setuptools’ plugins.  See this comment(3) for more context on
     the motivation for this change.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1083

   (2) http://doc.devpi.net/latest/

   (3) 
https://bitbucket.org/hpk42/devpi/issues/388/support-rtd-model-for-building-uploading#comment-34292423


File: setuptools.info,  Node: v36 0 1,  Next: v36 0 0,  Prev: v36 1 0,  Up: History<2>

9.123 v36.0.1
=============

01 Jun 2017

   * #1042(1): Fix import in py27compat module that still referenced six
     directly, rather than through the externs module (vendored packages
     hook).

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1042


File: setuptools.info,  Node: v36 0 0,  Next: v35 0 2,  Prev: v36 0 1,  Up: History<2>

9.124 v36.0.0
=============

30 May 2017

   * #980(1) and others: Once again, Setuptools vendors all of its
     dependencies.  It seems to be the case that in the Python
     ecosystem, all build tools must run without any dependencies
     (build, runtime, or otherwise).  At such a point that a mechanism
     exists that allows build tools to have dependencies, Setuptools
     will adopt it.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/980


File: setuptools.info,  Node: v35 0 2,  Next: v35 0 1,  Prev: v36 0 0,  Up: History<2>

9.125 v35.0.2
=============

27 Apr 2017

   * #1015(1): Fix test failures on Python 3.7.

   * #1024(2): Add workaround for Jython #2581(3) in monkey module.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1015

   (2) https://github.com/pypa/setuptools/issues/1024

   (3) http://bugs.jython.org/issue2581


File: setuptools.info,  Node: v35 0 1,  Next: v35 0 0,  Prev: v35 0 2,  Up: History<2>

9.126 v35.0.1
=============

18 Apr 2017

   * #992(1): Revert change introduced in v34.4.1, now considered
     invalid.

   * #1016(2): Revert change introduced in v35.0.0 per #1014(3),
     referencing #436(4).  The approach had unintended consequences,
     causing sdist installs to be missing files.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/992

   (2) https://github.com/pypa/setuptools/issues/1016

   (3) https://github.com/pypa/setuptools/issues/1014

   (4) https://github.com/pypa/setuptools/issues/436


File: setuptools.info,  Node: v35 0 0,  Next: v34 4 1,  Prev: v35 0 1,  Up: History<2>

9.127 v35.0.0
=============

15 Apr 2017

   * #436(1): In egg_info.manifest_maker, no longer read the file list
     from the manifest file, and instead re-build it on each build.  In
     this way, files removed from the specification will not linger in
     the manifest.  As a result, any files manually added to the
     manifest will be removed on subsequent egg_info invocations.  No
     projects should be manually adding files to the manifest and should
     instead use MANIFEST.in or SCM file finders to force inclusion of
     files in the manifest.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/436


File: setuptools.info,  Node: v34 4 1,  Next: v34 4 0,  Prev: v35 0 0,  Up: History<2>

9.128 v34.4.1
=============

10 Apr 2017

   * #1008(1): In MSVC support, use always the last version available
     for Windows SDK and UCRT SDK.

   * #1008(2): In MSVC support, fix “vcruntime140.dll” returned path
     with Visual Studio 2017.

   * #992(3): In msvc.msvc9_query_vcvarsall, ensure the returned dicts
     have str values and not Unicode for compatibility with os.environ.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1008

   (2) https://github.com/pypa/setuptools/issues/1008

   (3) https://github.com/pypa/setuptools/issues/992


File: setuptools.info,  Node: v34 4 0,  Next: v34 3 3,  Prev: v34 4 1,  Up: History<2>

9.129 v34.4.0
=============

07 Apr 2017

   * #995(1): In MSVC support, add support for “Microsoft Visual Studio
     2017” and “Microsoft Visual Studio Build Tools 2017”.

   * #999(2) via #1007(3): Extend support for declarative package config
     in a setup.cfg file to include the options ‘python_requires’ and
     ‘py_modules’.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/995

   (2) https://github.com/pypa/setuptools/issues/999

   (3) https://github.com/pypa/setuptools/issues/1007


File: setuptools.info,  Node: v34 3 3,  Next: v34 3 2,  Prev: v34 4 0,  Up: History<2>

9.130 v34.3.3
=============

26 Mar 2017

   * #967(1) (and #997(2)): Explicitly import submodules of packaging to
     account for environments where the imports of those submodules is
     not implied by other behavior.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/967

   (2) https://github.com/pypa/setuptools/issues/997


File: setuptools.info,  Node: v34 3 2,  Next: v34 3 1,  Prev: v34 3 3,  Up: History<2>

9.131 v34.3.2
=============

11 Mar 2017

   * #993(1): Fix documentation upload by correcting rendering of
     content-type in _build_multipart on Python 3.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/993


File: setuptools.info,  Node: v34 3 1,  Next: v34 3 0,  Prev: v34 3 2,  Up: History<2>

9.132 v34.3.1
=============

02 Mar 2017

   * #988(1): Trap ‘os.unlink’ same as ‘os.remove’ in ‘auto_chmod’ error
     handler.

   * #983(2): Fixes to invalid escape sequence deprecations on Python
     3.6.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/988

   (2) https://github.com/pypa/setuptools/issues/983


File: setuptools.info,  Node: v34 3 0,  Next: v34 2 0,  Prev: v34 3 1,  Up: History<2>

9.133 v34.3.0
=============

23 Feb 2017

   * #941(1): In the upload command, if the username is blank, default
     to ‘getpass.getuser()’.

   * #971(2): Correct distutils findall monkeypatch to match appropriate
     versions (namely Python 3.4.6).

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/941

   (2) https://github.com/pypa/setuptools/issues/971


File: setuptools.info,  Node: v34 2 0,  Next: v34 1 1,  Prev: v34 3 0,  Up: History<2>

9.134 v34.2.0
=============

12 Feb 2017

   * #966(1): Add support for reading dist-info metadata and thus
     locating Distributions from zip files.

   * #968(2): Allow ‘+’ and ‘!’ in egg fragments so that it can take
     package names that contain PEP 440(3) conforming version
     specifiers.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/966

   (2) https://github.com/pypa/setuptools/issues/968

   (3) https://www.python.org/dev/peps/pep-0440/


File: setuptools.info,  Node: v34 1 1,  Next: v34 1 0,  Prev: v34 2 0,  Up: History<2>

9.135 v34.1.1
=============

03 Feb 2017

   * #953(1): More aggressively employ the compatibility issue
     originally added in #706(2).

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/953

   (2) https://github.com/pypa/setuptools/issues/706


File: setuptools.info,  Node: v34 1 0,  Next: v34 0 3,  Prev: v34 1 1,  Up: History<2>

9.136 v34.1.0
=============

28 Jan 2017

   * #930(1): ‘build_info’ now accepts two new parameters to optimize
     and customize the building of C libraries.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/930


File: setuptools.info,  Node: v34 0 3,  Next: v34 0 2,  Prev: v34 1 0,  Up: History<2>

9.137 v34.0.3
=============

28 Jan 2017

   * #947(1): Loosen restriction on the version of six required,
     restoring compatibility with environments relying on six 1.6.0 and
     later.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/947


File: setuptools.info,  Node: v34 0 2,  Next: v34 0 1,  Prev: v34 0 3,  Up: History<2>

9.138 v34.0.2
=============

24 Jan 2017

   * #882(1): Ensure extras are honored when building the working set.

   * #913(2): Fix issue in develop if package directory has a trailing
     slash.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/882

   (2) https://github.com/pypa/setuptools/issues/913


File: setuptools.info,  Node: v34 0 1,  Next: v34 0 0,  Prev: v34 0 2,  Up: History<2>

9.139 v34.0.1
=============

23 Jan 2017

   * #935(1): Fix glob syntax in graft.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/935


File: setuptools.info,  Node: v34 0 0,  Next: v33 1 1,  Prev: v34 0 1,  Up: History<2>

9.140 v34.0.0
=============

23 Jan 2017

   * #581(1): Instead of vendoring the growing list of dependencies that
     Setuptools requires to function, Setuptools now requires these
     dependencies just like any other project.  Unlike other projects,
     however, Setuptools cannot rely on ‘setup_requires’ to demand the
     dependencies it needs to install because its own machinery would be
     necessary to pull those dependencies if not present (a
     bootstrapping problem).  As a result, Setuptools no longer supports
     self upgrade or installation in the general case.  Instead, users
     are directed to use pip to install and upgrade using the ‘wheel’
     distributions of setuptools.

     Users are welcome to contrive other means to install or upgrade
     Setuptools using other means, such as pre-installing the Setuptools
     dependencies with pip or a bespoke bootstrap tool, but such usage
     is not recommended and is not supported.

     As discovered in #940(2), not all versions of pip will successfully
     install Setuptools from its pre-built wheel.  If you encounter
     issues with “No module named six” or “No module named packaging”,
     especially following a line “Running setup.py egg_info for package
     setuptools”, then your pip is not new enough.

     There’s an additional issue in pip where setuptools is upgraded
     concurrently with other source packages, described in pip #4253(3).
     The proposed workaround is to always upgrade Setuptools first prior
     to upgrading other packages that would upgrade Setuptools.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/581

   (2) https://github.com/pypa/setuptools/issues/940

   (3) https://github.com/pypa/setuptools/issues/4253


File: setuptools.info,  Node: v33 1 1,  Next: v33 1 0,  Prev: v34 0 0,  Up: History<2>

9.141 v33.1.1
=============

16 Jan 2017

   * #921(1): Correct issue where certifi fallback not being reached on
     Windows.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/921


File: setuptools.info,  Node: v33 1 0,  Next: v33 0 0,  Prev: v33 1 1,  Up: History<2>

9.142 v33.1.0
=============

15 Jan 2017

Installation via pip, as indicated in the Python Packaging User’s
Guide(1), is the officially-supported mechanism for installing
Setuptools, and this recommendation is now explicit in the much more
concise README.

Other edits and tweaks were made to the documentation.  The codebase is
unchanged.

   ---------- Footnotes ----------

   (1) https://packaging.python.org/installing/


File: setuptools.info,  Node: v33 0 0,  Next: v32 3 1,  Prev: v33 1 0,  Up: History<2>

9.143 v33.0.0
=============

01 Jan 2017

   * #619(1): Removed support for the ‘tag_svn_revision’ distribution
     option.  If Subversion tagging support is still desired, consider
     adding the functionality to setuptools_svn in setuptools_svn #2(2).

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/619

   (2) https://github.com/jaraco/setuptools_svn/issues/2


File: setuptools.info,  Node: v32 3 1,  Next: v32 3 0,  Prev: v33 0 0,  Up: History<2>

9.144 v32.3.1
=============

28 Dec 2016

   * #866(1): Use ‘dis.Bytecode’ on Python 3.4 and later in
     ‘setuptools.depends’.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/866


File: setuptools.info,  Node: v32 3 0,  Next: v32 2 0,  Prev: v32 3 1,  Up: History<2>

9.145 v32.3.0
=============

24 Dec 2016

   * #889(1): Backport proposed fix for disabling interpolation in
     distutils.Distribution.parse_config_files.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/889


File: setuptools.info,  Node: v32 2 0,  Next: v32 1 3,  Prev: v32 3 0,  Up: History<2>

9.146 v32.2.0
=============

22 Dec 2016

   * #884(1): Restore support for running the tests under
     pytest-runner(2) by ensuring that PYTHONPATH is honored in tests
     invoking a subprocess.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/884

   (2) https://github.com/pytest-dev/pytest-runner


File: setuptools.info,  Node: v32 1 3,  Next: v32 1 2,  Prev: v32 2 0,  Up: History<2>

9.147 v32.1.3
=============

21 Dec 2016

   * #706(1): Add rmtree compatibility shim for environments where
     rmtree fails when passed a unicode string.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/706


File: setuptools.info,  Node: v32 1 2,  Next: v32 1 1,  Prev: v32 1 3,  Up: History<2>

9.148 v32.1.2
=============

18 Dec 2016

   * #893(1): Only release sdist in zip format as warehouse now
     disallows releasing two different formats.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/893


File: setuptools.info,  Node: v32 1 1,  Next: v32 1 0,  Prev: v32 1 2,  Up: History<2>

9.149 v32.1.1
=============

18 Dec 2016

   * #704(1): More selectively ensure that ‘rmtree’ is not invoked with
     a byte string, enabling it to remove files that are non-ascii, even
     on Python 2.

   * #712(2): In ‘sandbox.run_setup’, ensure that ‘__file__’ is always a
     ‘str’, modeling the behavior observed by the interpreter when
     invoking scripts and modules.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/704

   (2) https://github.com/pypa/setuptools/issues/712


File: setuptools.info,  Node: v32 1 0,  Next: v32 0 0,  Prev: v32 1 1,  Up: History<2>

9.150 v32.1.0
=============

16 Dec 2016

   * #891(1): In ‘test’ command on test failure, raise DistutilsError,
     suppression invocation of subsequent commands.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/891


File: setuptools.info,  Node: v32 0 0,  Next: v31 0 1,  Prev: v32 1 0,  Up: History<2>

9.151 v32.0.0
=============

14 Dec 2016

   * #890(1): Revert #849(2).  ‘global-exclude .foo’ will not match all
     ‘*.foo’ files any more.  Package authors must add an explicit
     wildcard, such as ‘global-exclude *.foo’, to match all ‘.foo’
     files.  See #886(3), #849(4).

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/890

   (2) https://github.com/pypa/setuptools/issues/849

   (3) https://github.com/pypa/setuptools/issues/886

   (4) https://github.com/pypa/setuptools/issues/849


File: setuptools.info,  Node: v31 0 1,  Next: v31 0 0,  Prev: v32 0 0,  Up: History<2>

9.152 v31.0.1
=============

14 Dec 2016

   * #885(1): Fix regression where ‘pkg_resources._rebuild_mod_path’
     would fail when a namespace package’s ‘__path__’ was not a list
     with a sort attribute.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/885


File: setuptools.info,  Node: v31 0 0,  Next: v30 4 0,  Prev: v31 0 1,  Up: History<2>

9.153 v31.0.0
=============

11 Dec 2016

   * #250(1): Install ‘-nspkg.pth’ files for packages installed with
     ‘setup.py develop’.  These .pth files allow namespace packages
     installed by pip or develop to co-mingle.  This change required the
     removal of the change for #805(2) and pip #1924(3), introduced in
     28.3.0 and implicated in #870(4), but means that namespace packages
     not in a site packages directory will no longer work on Python
     earlier than 3.5, whereas before they would work on Python not
     earlier than 3.3.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/250

   (2) https://github.com/pypa/setuptools/issues/805

   (3) https://github.com/pypa/setuptools/issues/1924

   (4) https://github.com/pypa/setuptools/issues/870


File: setuptools.info,  Node: v30 4 0,  Next: v30 3 0,  Prev: v31 0 0,  Up: History<2>

9.154 v30.4.0
=============

10 Dec 2016

   * #879(1): For declarative config:

        - read_configuration() now accepts ignore_option_errors
          argument.  This allows scraping tools to read metadata without
          a need to download entire packages.  E.g.  we can gather some
          stats right from GitHub repos just by downloading setup.cfg.

        - packages find: directive now supports fine tuning from a
          subsection.  The same arguments as for find() are accepted.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/879


File: setuptools.info,  Node: v30 3 0,  Next: v30 2 1,  Prev: v30 4 0,  Up: History<2>

9.155 v30.3.0
=============

08 Dec 2016

   * #394(1) via #862(2): Added support for declarative package config
     in a setup.cfg file(3).

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/394

   (2) https://github.com/pypa/setuptools/issues/862

   (3) 
https://setuptools.readthedocs.io/en/latest/setuptools.html#configuring-setup-using-setup-cfg-files


File: setuptools.info,  Node: v30 2 1,  Next: v30 2 0,  Prev: v30 3 0,  Up: History<2>

9.156 v30.2.1
=============

08 Dec 2016

   * #850(1): In test command, invoke unittest.main with indication not
     to exit the process.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/850


File: setuptools.info,  Node: v30 2 0,  Next: v30 1 0,  Prev: v30 2 1,  Up: History<2>

9.157 v30.2.0
=============

04 Dec 2016

   * #854(1): Bump to vendored Packaging 16.8(2).

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/854

   (2) https://github.com/pypa/packaging/blob/16.8/CHANGELOG.rst


File: setuptools.info,  Node: v30 1 0,  Next: v30 0 0,  Prev: v30 2 0,  Up: History<2>

9.158 v30.1.0
=============

03 Dec 2016

   * #846(1): Also trap ‘socket.error’ when opening URLs in
     package_index.

   * #849(2): Manifest processing now matches the filename pattern
     anywhere in the filename and not just at the start.  Restores
     behavior found prior to 28.5.0.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/846

   (2) https://github.com/pypa/setuptools/issues/849


File: setuptools.info,  Node: v30 0 0,  Next: v29 0 1,  Prev: v30 1 0,  Up: History<2>

9.159 v30.0.0
=============

01 Dec 2016

   * #864(1): Drop support for Python 3.2.  Systems requiring Python 3.2
     support must use ‘setuptools < 30’.

   * #825(2): Suppress warnings for single files.

   * #830(3) via #843(4): Once again restored inclusion of data files to
     sdists, but now trap TypeError caused by techniques employed rjsmin
     and similar.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/864

   (2) https://github.com/pypa/setuptools/issues/825

   (3) https://github.com/pypa/setuptools/issues/830

   (4) https://github.com/pypa/setuptools/issues/843


File: setuptools.info,  Node: v29 0 1,  Next: v29 0 0,  Prev: v30 0 0,  Up: History<2>

9.160 v29.0.1
=============

26 Nov 2016

   * #861(1): Re-release of v29.0.1 with the executable script launchers
     bundled.  Now, launchers are included by default and users that
     want to disable this behavior must set the environment variable
     ‘SETUPTOOLS_INSTALL_WINDOWS_SPECIFIC_FILES’ to a false value like
     “false” or “0”.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/861


File: setuptools.info,  Node: v29 0 0,  Next: v28 8 0,  Prev: v29 0 1,  Up: History<2>

9.161 v29.0.0
=============

25 Nov 2016

   * #841(1): Drop special exception for packages invoking win32com
     during the build/install process.  See Distribute #118(2) for
     history.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/841

   (2) https://bitbucket.org/tarek/distribute/issue/118


File: setuptools.info,  Node: v28 8 0,  Next: v28 7 1,  Prev: v29 0 0,  Up: History<2>

9.162 v28.8.0
=============

04 Nov 2016

   * #629(1): Per the discussion, refine the sorting to use version
     value order for more accurate detection of the latest available
     version when scanning for packages.  See also #829(2).

   * #837(3): Rely on the config var “SO” for Python 3.3.0 only when
     determining the ext filename.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/629

   (2) https://github.com/pypa/setuptools/issues/829

   (3) https://github.com/pypa/setuptools/issues/837


File: setuptools.info,  Node: v28 7 1,  Next: v28 7 0,  Prev: v28 8 0,  Up: History<2>

9.163 v28.7.1
=============

29 Oct 2016

   * #827(1): Update PyPI root for dependency links.

   * #833(2): Backed out changes from #830(3) as the implementation
     seems to have problems in some cases.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/827

   (2) https://github.com/pypa/setuptools/issues/833

   (3) https://github.com/pypa/setuptools/issues/830


File: setuptools.info,  Node: v28 7 0,  Next: v28 6 1,  Prev: v28 7 1,  Up: History<2>

9.164 v28.7.0
=============

28 Oct 2016

   * #832(1): Moved much of the namespace package handling functionality
     into a separate module for re-use in something like #789(2).

   * #830(3): ‘sdist’ command no longer suppresses the inclusion of data
     files, re-aligning with the expectation of distutils and addressing
     #274(4) and #521(5).

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/832

   (2) https://github.com/pypa/setuptools/issues/789

   (3) https://github.com/pypa/setuptools/issues/830

   (4) https://github.com/pypa/setuptools/issues/274

   (5) https://github.com/pypa/setuptools/issues/521


File: setuptools.info,  Node: v28 6 1,  Next: v28 6 0,  Prev: v28 7 0,  Up: History<2>

9.165 v28.6.1
=============

19 Oct 2016

   * #816(1): Fix manifest file list order in tests.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/816


File: setuptools.info,  Node: v28 6 0,  Next: v28 5 0,  Prev: v28 6 1,  Up: History<2>

9.166 v28.6.0
=============

16 Oct 2016

   * #629(1): When scanning for packages, ‘pkg_resources’ now ignores
     empty egg-info directories and gives precedence to packages whose
     versions are lexicographically greatest, a rough approximation for
     preferring the latest available version.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/629


File: setuptools.info,  Node: v28 5 0,  Next: v28 4 0,  Prev: v28 6 0,  Up: History<2>

9.167 v28.5.0
=============

14 Oct 2016

   * #810(1): Tests are now invoked with tox and not setup.py test.

   * #249(2) and #450(3) via #764(4): Avoid scanning the whole tree when
     building the manifest.  Also fixes a long-standing bug where
     patterns in ‘MANIFEST.in’ had implicit wildcard matching.  This
     caused ‘global-exclude .foo’ to exclude all ‘*.foo’ files, but also
     ‘global-exclude bar.py’ to exclude ‘foo_bar.py’.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/810

   (2) https://github.com/pypa/setuptools/issues/249

   (3) https://github.com/pypa/setuptools/issues/450

   (4) https://github.com/pypa/setuptools/issues/764


File: setuptools.info,  Node: v28 4 0,  Next: v28 3 0,  Prev: v28 5 0,  Up: History<2>

9.168 v28.4.0
=============

14 Oct 2016

   * #732(1): Now extras with a hyphen are honored per PEP 426(2).

   * #811(3): Update to pyparsing 2.1.10.

   * Updated ‘setuptools.command.sdist’ to re-use most of the
     functionality directly from ‘distutils.command.sdist’ for the
     ‘add_defaults’ method with strategic overrides.  See #750(4) for
     rationale.

   * #760(5) via #762(6): Look for certificate bundle where SUSE Linux
     typically presents it.  Use ‘certifi.where()’ to locate the bundle.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/732

   (2) https://www.python.org/dev/peps/pep-0426/

   (3) https://github.com/pypa/setuptools/issues/811

   (4) https://github.com/pypa/setuptools/issues/750

   (5) https://github.com/pypa/setuptools/issues/760

   (6) https://github.com/pypa/setuptools/issues/762


File: setuptools.info,  Node: v28 3 0,  Next: v28 1 0,  Prev: v28 4 0,  Up: History<2>

9.169 v28.3.0
=============

07 Oct 2016

   * #809(1): In ‘find_packages()’, restore support for excluding a
     parent package without excluding a child package.

   * #805(2): Disable ‘-nspkg.pth’ behavior on Python 3.3+ where
     PEP-420(3) functionality is adequate.  Fixes pip #1924(4).

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/809

   (2) https://github.com/pypa/setuptools/issues/805

   (3) https://www.python.org/dev/peps/pep-0420/

   (4) https://github.com/pypa/setuptools/issues/1924


File: setuptools.info,  Node: v28 1 0,  Next: v28 0 0,  Prev: v28 3 0,  Up: History<2>

9.170 v28.1.0
=============

01 Oct 2016

   * #803(1): Bump certifi to 2016.9.26.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/803


File: setuptools.info,  Node: v28 0 0,  Next: v27 3 1,  Prev: v28 1 0,  Up: History<2>

9.171 v28.0.0
=============

27 Sep 2016

   * #733(1): Do not search excluded directories for packages.  This
     introduced a backwards incompatible change in ‘find_packages()’ so
     that ‘find_packages(exclude=['foo']) == []’, excluding subpackages
     of ‘foo’.  Previously, ‘find_packages(exclude=['foo']) ==
     ['foo.bar']’, even though the parent ‘foo’ package was excluded.

   * #795(2): Bump certifi.

   * #719(3): Suppress decoding errors and instead log a warning when
     metadata cannot be decoded.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/733

   (2) https://github.com/pypa/setuptools/issues/795

   (3) https://github.com/pypa/setuptools/issues/719


File: setuptools.info,  Node: v27 3 1,  Next: v27 3 0,  Prev: v28 0 0,  Up: History<2>

9.172 v27.3.1
=============

27 Sep 2016

   * #790(1): In MSVC monkeypatching, explicitly patch each function by
     name in the target module instead of inferring the module from the
     function’s ‘__module__’.  Improves compatibility with other
     packages that might have previously patched distutils functions
     (i.e.  NumPy).

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/790


File: setuptools.info,  Node: v27 3 0,  Next: v27 2 0,  Prev: v27 3 1,  Up: History<2>

9.173 v27.3.0
=============

20 Sep 2016

   * #794(1): In test command, add installed eggs to PYTHONPATH when
     invoking tests so that subprocesses will also have the dependencies
     available.  Fixes tox 330(2).

   * #795(3): Update vendored pyparsing 2.1.9.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/794

   (2) https://github.com/tox-dev/tox/issues/330

   (3) https://github.com/pypa/setuptools/issues/795


File: setuptools.info,  Node: v27 2 0,  Next: v27 1 2,  Prev: v27 3 0,  Up: History<2>

9.174 v27.2.0
=============

14 Sep 2016

   * #520(1) and #513(2): Suppress ValueErrors in
     fixup_namespace_packages when lookup fails.

   * Nicer, more consistent interfaces for msvc monkeypatching.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/520

   (2) https://github.com/pypa/setuptools/issues/513


File: setuptools.info,  Node: v27 1 2,  Next: v27 1 1,  Prev: v27 2 0,  Up: History<2>

9.175 v27.1.2
=============

09 Sep 2016

   * #779(1) via #781(2): Fix circular import.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/779

   (2) https://github.com/pypa/setuptools/issues/781


File: setuptools.info,  Node: v27 1 1,  Next: v27 1 0,  Prev: v27 1 2,  Up: History<2>

9.176 v27.1.1
=============

09 Sep 2016

   * #778(1): Fix MSVC monkeypatching.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/778


File: setuptools.info,  Node: v27 1 0,  Next: v27 0 0,  Prev: v27 1 1,  Up: History<2>

9.177 v27.1.0
=============

09 Sep 2016

   * Introduce the (private) ‘monkey’ module to encapsulate the
     distutils monkeypatching behavior.


File: setuptools.info,  Node: v27 0 0,  Next: v26 1 1,  Prev: v27 1 0,  Up: History<2>

9.178 v27.0.0
=============

09 Sep 2016

   * Now use Warehouse by default for ‘upload’, patching
     ‘distutils.config.PyPIRCCommand’ to affect default behavior.

     Any config in .pypirc should be updated to replace

          ‘https://pypi.python.org/pypi/’

     with

          ‘https://upload.pypi.org/legacy/’

     Similarly, any passwords stored in the keyring should be updated to
     use this new value for “system”.

     The ‘upload_docs’ command will continue to use the python.org site,
     but the command is now deprecated.  Users are urged to use Read The
     Docs instead.

   * #776(1): Use EXT_SUFFIX for py_limited_api renaming.

   * #774(2) and #775(3): Use LegacyVersion from packaging when
     detecting numpy versions.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/776

   (2) https://github.com/pypa/setuptools/issues/774

   (3) https://github.com/pypa/setuptools/issues/775


File: setuptools.info,  Node: v26 1 1,  Next: v26 1 0,  Prev: v27 0 0,  Up: History<2>

9.179 v26.1.1
=============

29 Aug 2016

   * Re-release of 26.1.0 with pytest pinned to allow for automated
     deployment and thus proper packaging environment variables, fixing
     issues with missing executable launchers.


File: setuptools.info,  Node: v26 1 0,  Next: v26 0 0,  Prev: v26 1 1,  Up: History<2>

9.180 v26.1.0
=============

28 Aug 2016

   * #763(1): ‘pkg_resources.get_default_cache’ now defers to the
     appdirs project(2) to resolve the cache directory.  Adds a vendored
     dependency on appdirs to pkg_resources.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/763

   (2) https://pypi.org/project/appdirs


File: setuptools.info,  Node: v26 0 0,  Next: v25 4 0,  Prev: v26 1 0,  Up: History<2>

9.181 v26.0.0
=============

20 Aug 2016

   * #748(1): By default, sdists are now produced in gzipped tarfile
     format by default on all platforms, adding forward compatibility
     for the same behavior in Python 3.6 (See Python #27819(2)).

   * #459(3) via #736(4): On Windows with script launchers, sys.argv[0]
     now reflects the name of the entry point, consistent with the
     behavior in distlib and pip wrappers.

   * #752(5) via #753(6): When indicating ‘py_limited_api’ to Extension,
     it must be passed as a keyword argument.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/748

   (2) http://bugs.python.org/issue27819

   (3) https://github.com/pypa/setuptools/issues/459

   (4) https://github.com/pypa/setuptools/issues/736

   (5) https://github.com/pypa/setuptools/issues/752

   (6) https://github.com/pypa/setuptools/issues/753


File: setuptools.info,  Node: v25 4 0,  Next: v25 3 0,  Prev: v26 0 0,  Up: History<2>

9.182 v25.4.0
=============

19 Aug 2016

   * Add Extension(py_limited_api=True).  When set to a truthy value,
     that extension gets a filename appropriate for code using
     Py_LIMITED_API. When used correctly this allows a single compiled
     extension to work on all future versions of CPython 3.  The
     py_limited_api argument only controls the filename.  To be
     compatible with multiple versions of Python 3, the C extension will
     also need to set -DPy_LIMITED_API=… and be modified to use only the
     functions in the limited API.


File: setuptools.info,  Node: v25 3 0,  Next: v25 2 0,  Prev: v25 4 0,  Up: History<2>

9.183 v25.3.0
=============

19 Aug 2016

   * #739(1) Fix unquoted libpaths by fixing compatibility between
     ‘numpy.distutils’ and ‘distutils._msvccompiler’ for numpy < 1.11.2
     (Fix issue #728(2), error also fixed in Numpy).

   * #731(3): Bump certifi.

   * Style updates.  See #740(4), #741(5), #743(6), #744(7), #742(8),
     #747(9).

   * #735(10): include license file.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/739

   (2) https://github.com/pypa/setuptools/issues/728

   (3) https://github.com/pypa/setuptools/issues/731

   (4) https://github.com/pypa/setuptools/issues/740

   (5) https://github.com/pypa/setuptools/issues/741

   (6) https://github.com/pypa/setuptools/issues/743

   (7) https://github.com/pypa/setuptools/issues/744

   (8) https://github.com/pypa/setuptools/issues/742

   (9) https://github.com/pypa/setuptools/issues/747

   (10) https://github.com/pypa/setuptools/issues/735


File: setuptools.info,  Node: v25 2 0,  Next: v25 1 6,  Prev: v25 3 0,  Up: History<2>

9.184 v25.2.0
=============

12 Aug 2016

   * #612(1) via #730(2): Add a LICENSE file which needs to be provided
     by the terms of the MIT license.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/612

   (2) https://github.com/pypa/setuptools/issues/730


File: setuptools.info,  Node: v25 1 6,  Next: v25 1 5,  Prev: v25 2 0,  Up: History<2>

9.185 v25.1.6
=============

05 Aug 2016

   * #725(1): revert ‘library_dir_option’ patch (Error is related to
     ‘numpy.distutils’ and make errors on non Numpy users).

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/725


File: setuptools.info,  Node: v25 1 5,  Next: v25 1 4,  Prev: v25 1 6,  Up: History<2>

9.186 v25.1.5
=============

05 Aug 2016

   * #720(1)

   * #723(2): Improve patch for ‘library_dir_option’.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/720

   (2) https://github.com/pypa/setuptools/issues/723


File: setuptools.info,  Node: v25 1 4,  Next: v25 1 3,  Prev: v25 1 5,  Up: History<2>

9.187 v25.1.4
=============

04 Aug 2016

   * #717(1)

   * #713(2)

   * #707(3): Fix Python 2 compatibility for MSVC by catching errors
     properly.

   * #715(4): Fix unquoted libpaths by patching ‘library_dir_option’.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/717

   (2) https://github.com/pypa/setuptools/issues/713

   (3) https://github.com/pypa/setuptools/issues/707

   (4) https://github.com/pypa/setuptools/issues/715


File: setuptools.info,  Node: v25 1 3,  Next: v25 1 2,  Prev: v25 1 4,  Up: History<2>

9.188 v25.1.3
=============

02 Aug 2016

   * #714(1) and #704(2): Revert fix as it breaks other components
     downstream that can’t handle unicode.  See #709(3), #710(4), and
     #712(5).

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/714

   (2) https://github.com/pypa/setuptools/issues/704

   (3) https://github.com/pypa/setuptools/issues/709

   (4) https://github.com/pypa/setuptools/issues/710

   (5) https://github.com/pypa/setuptools/issues/712


File: setuptools.info,  Node: v25 1 2,  Next: v25 1 1,  Prev: v25 1 3,  Up: History<2>

9.189 v25.1.2
=============

01 Aug 2016

   * #704(1): Fix errors when installing a zip sdist that contained
     files named with non-ascii characters on Windows would crash the
     install when it attempted to clean up the build.

   * #646(2): MSVC compatibility - catch errors properly in
     RegistryInfo.lookup.

   * #702(3): Prevent UnboundLocalError when initial working_set is
     empty.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/704

   (2) https://github.com/pypa/setuptools/issues/646

   (3) https://github.com/pypa/setuptools/issues/702


File: setuptools.info,  Node: v25 1 1,  Next: v25 1 0,  Prev: v25 1 2,  Up: History<2>

9.190 v25.1.1
=============

28 Jul 2016

   * #686(1): Fix issue in sys.path ordering by pkg_resources when
     rewrite technique is “raw”.

   * #699(2): Fix typo in msvc support.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/686

   (2) https://github.com/pypa/setuptools/issues/699


File: setuptools.info,  Node: v25 1 0,  Next: v25 0 2,  Prev: v25 1 1,  Up: History<2>

9.191 v25.1.0
=============

25 Jul 2016

   * #609(1): Setuptools will now try to download a distribution from
     the next possible download location if the first download fails.
     This means you can now specify multiple links as ‘dependency_links’
     and all links will be tried until a working download link is
     encountered.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/609


File: setuptools.info,  Node: v25 0 2,  Next: v25 0 1,  Prev: v25 1 0,  Up: History<2>

9.192 v25.0.2
=============

25 Jul 2016

   * #688(1): Fix AttributeError in setup.py when invoked not from the
     current directory.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/688


File: setuptools.info,  Node: v25 0 1,  Next: v25 0 0,  Prev: v25 0 2,  Up: History<2>

9.193 v25.0.1
=============

25 Jul 2016

   * Cleanup of setup.py script.

   * Fixed documentation builders by allowing setup.py to be imported
     without having bootstrapped the metadata.

   * More style cleanup.  See #677(1), #678(2), #679(3), #681(4),
     #685(5).

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/677

   (2) https://github.com/pypa/setuptools/issues/678

   (3) https://github.com/pypa/setuptools/issues/679

   (4) https://github.com/pypa/setuptools/issues/681

   (5) https://github.com/pypa/setuptools/issues/685


File: setuptools.info,  Node: v25 0 0,  Next: v24 3 1,  Prev: v25 0 1,  Up: History<2>

9.194 v25.0.0
=============

23 Jul 2016

   * #674(1): Default ‘sys.path’ manipulation by easy-install.pth is now
     “raw”, meaning that when writing easy-install.pth during any
     install operation, the ‘sys.path’ will not be rewritten and will no
     longer give preference to easy_installed packages.

     To retain the old behavior when using any easy_install operation
     (including ‘setup.py install’ when setuptools is present), set the
     environment variable:

          SETUPTOOLS_SYS_PATH_TECHNIQUE=rewrite

     This project hopes that that few if any environments find it
     necessary to retain the old behavior, and intends to drop support
     for it altogether in a future release.  Please report any relevant
     concerns in the ticket for this change.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/674


File: setuptools.info,  Node: v24 3 1,  Next: v24 3 0,  Prev: v25 0 0,  Up: History<2>

9.195 v24.3.1
=============

23 Jul 2016

   * #398(1): Fix shebang handling on Windows in script headers where
     spaces in ‘sys.executable’ would produce an improperly-formatted
     shebang header, introduced in 12.0 with the fix for #188(2).

   * #663(3), #670(4): More style updates.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/398

   (2) https://github.com/pypa/setuptools/issues/188

   (3) https://github.com/pypa/setuptools/issues/663

   (4) https://github.com/pypa/setuptools/issues/670


File: setuptools.info,  Node: v24 3 0,  Next: v24 2 1,  Prev: v24 3 1,  Up: History<2>

9.196 v24.3.0
=============

21 Jul 2016

   * #516(1): Disable ‘os.link’ to avoid hard linking in
     ‘sdist.make_distribution’, avoiding errors on systems that support
     hard links but not on the file system in which the build is
     occurring.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/516


File: setuptools.info,  Node: v24 2 1,  Next: v24 2 0,  Prev: v24 3 0,  Up: History<2>

9.197 v24.2.1
=============

21 Jul 2016

   * #667(1): Update Metadata-Version to 1.2 when ‘python_requires’ is
     supplied.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/667


File: setuptools.info,  Node: v24 2 0,  Next: v24 1 1,  Prev: v24 2 1,  Up: History<2>

9.198 v24.2.0
=============

20 Jul 2016

   * #631(1): Add support for ‘python_requires’ keyword.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/631


File: setuptools.info,  Node: v24 1 1,  Next: v24 1 0,  Prev: v24 2 0,  Up: History<2>

9.199 v24.1.1
=============

20 Jul 2016

   * More style updates.  See #660(1), #661(2), #641(3).

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/660

   (2) https://github.com/pypa/setuptools/issues/661

   (3) https://github.com/pypa/setuptools/issues/641


File: setuptools.info,  Node: v24 1 0,  Next: v24 0 3,  Prev: v24 1 1,  Up: History<2>

9.200 v24.1.0
=============

20 Jul 2016

   * #659(1): ‘setup.py’ now will fail fast and with a helpful error
     message when the necessary metadata is missing.

   * More style updates.  See #656(2), #635(3), #640(4), #644(5),
     #650(6), #652(7), and #655(8).

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/659

   (2) https://github.com/pypa/setuptools/issues/656

   (3) https://github.com/pypa/setuptools/issues/635

   (4) https://github.com/pypa/setuptools/issues/640

   (5) https://github.com/pypa/setuptools/issues/644

   (6) https://github.com/pypa/setuptools/issues/650

   (7) https://github.com/pypa/setuptools/issues/652

   (8) https://github.com/pypa/setuptools/issues/655


File: setuptools.info,  Node: v24 0 3,  Next: v24 0 2,  Prev: v24 1 0,  Up: History<2>

9.201 v24.0.3
=============

14 Jul 2016

   * Updated style in much of the codebase to match community
     expectations.  See #632(1), #633(2), #634(3), #637(4), #639(5),
     #638(6), #642(7), #648(8).

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/632

   (2) https://github.com/pypa/setuptools/issues/633

   (3) https://github.com/pypa/setuptools/issues/634

   (4) https://github.com/pypa/setuptools/issues/637

   (5) https://github.com/pypa/setuptools/issues/639

   (6) https://github.com/pypa/setuptools/issues/638

   (7) https://github.com/pypa/setuptools/issues/642

   (8) https://github.com/pypa/setuptools/issues/648


File: setuptools.info,  Node: v24 0 2,  Next: v24 0 1,  Prev: v24 0 3,  Up: History<2>

9.202 v24.0.2
=============

04 Jul 2016

   * If MSVC++14 is needed ‘setuptools.msvc’ now redirect user to Visual
     C++ Build Tools web page.


File: setuptools.info,  Node: v24 0 1,  Next: v24 0 0,  Prev: v24 0 2,  Up: History<2>

9.203 v24.0.1
=============

03 Jul 2016

   * #625(1) and #626(2): Fixes on ‘setuptools.msvc’ mainly for Python 2
     and Linux.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/625

   (2) https://github.com/pypa/setuptools/issues/626


File: setuptools.info,  Node: v24 0 0,  Next: v23 2 1,  Prev: v24 0 1,  Up: History<2>

9.204 v24.0.0
=============

02 Jul 2016

   * Pull Request #174(1): Add more aggressive support for standalone
     Microsoft Visual C++ compilers in msvc9compiler patch.
     Particularly : Windows SDK 6.1 and 7.0 (MSVC++ 9.0), Windows SDK
     7.1 (MSVC++ 10.0), Visual C++ Build Tools 2015 (MSVC++14)

   * Renamed ‘setuptools.msvc9_support’ to ‘setuptools.msvc’.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/174


File: setuptools.info,  Node: v23 2 1,  Next: v23 1 0,  Prev: v24 0 0,  Up: History<2>

9.205 v23.2.1
=============

02 Jul 2016

Re-release of v23.2.0, which was missing the intended commits.

   * #623(1): Remove used of deprecated ‘U’ flag when reading manifests.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/623


File: setuptools.info,  Node: v23 1 0,  Next: v23 0 0,  Prev: v23 2 1,  Up: History<2>

9.206 v23.1.0
=============

24 Jun 2016

   * #619(1): Deprecated ‘tag_svn_revision’ distribution option.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/619


File: setuptools.info,  Node: v23 0 0,  Next: v22 0 5,  Prev: v23 1 0,  Up: History<2>

9.207 v23.0.0
=============

09 Jun 2016

   * #611(1): Removed ARM executables for CLI and GUI script launchers
     on Windows.  If this was a feature you cared about, please comment
     in the ticket.

   * #604(2): Removed docs building support.  The project now relies on
     documentation hosted at ‘https://setuptools.readthedocs.io/’.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/611

   (2) https://github.com/pypa/setuptools/issues/604


File: setuptools.info,  Node: v22 0 5,  Next: v22 0 4,  Prev: v23 0 0,  Up: History<2>

9.208 v22.0.5
=============

03 Jun 2016

   * #604(1): Restore repository for upload_docs command to restore
     publishing of docs during release.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/604


File: setuptools.info,  Node: v22 0 4,  Next: v22 0 3,  Prev: v22 0 5,  Up: History<2>

9.209 v22.0.4
=============

03 Jun 2016

   * #589(1): Upload releases to pypi.io using the upload hostname and
     legacy path.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/589


File: setuptools.info,  Node: v22 0 3,  Next: v22 0 2,  Prev: v22 0 4,  Up: History<2>

9.210 v22.0.3
=============

03 Jun 2016

   * #589(1): Releases are now uploaded to pypi.io (Warehouse) even when
     releases are made on Twine via Travis.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/589


File: setuptools.info,  Node: v22 0 2,  Next: v22 0 1,  Prev: v22 0 3,  Up: History<2>

9.211 v22.0.2
=============

03 Jun 2016

   * #589(1): Releases are now uploaded to pypi.io (Warehouse).

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/589


File: setuptools.info,  Node: v22 0 1,  Next: v22 0 0,  Prev: v22 0 2,  Up: History<2>

9.212 v22.0.1
=============

03 Jun 2016

   * #190(1): On Python 2, if unicode is passed for packages to
     ‘build_py’ command, it will be handled just as with text on Python
     3.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/190


File: setuptools.info,  Node: v22 0 0,  Next: v21 2 2,  Prev: v22 0 1,  Up: History<2>

9.213 v22.0.0
=============

01 Jun 2016

Intended to be v21.3.0, but jaraco accidentally released as a major
bump.

   * #598(1): Setuptools now lists itself first in the User-Agent for
     web requests, better following the guidelines in RFC 7231(2).

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/598

   (2) https://tools.ietf.org/html/rfc7231#section-5.5.3


File: setuptools.info,  Node: v21 2 2,  Next: v21 2 1,  Prev: v22 0 0,  Up: History<2>

9.214 v21.2.2
=============

29 May 2016

   * Minor fixes to changelog and docs.


File: setuptools.info,  Node: v21 2 1,  Next: v21 2 0,  Prev: v21 2 2,  Up: History<2>

9.215 v21.2.1
=============

22 May 2016

   * #261(1): Exclude directories when resolving globs in package_data.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/261


File: setuptools.info,  Node: v21 2 0,  Next: v21 1 0,  Prev: v21 2 1,  Up: History<2>

9.216 v21.2.0
=============

21 May 2016

   * #539(1): In the easy_install get_site_dirs, honor all paths found
     in ‘site.getsitepackages’.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/539


File: setuptools.info,  Node: v21 1 0,  Next: v21 0 0,  Prev: v21 2 0,  Up: History<2>

9.217 v21.1.0
=============

18 May 2016

   * #572(1): In build_ext, now always import ‘_CONFIG_VARS’ from
     ‘distutils’ rather than from ‘sysconfig’ to allow
     ‘distutils.sysconfig.customize_compiler’ configure the OS X
     compiler for ‘-dynamiclib’.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/572


File: setuptools.info,  Node: v21 0 0,  Next: v20 10 0,  Prev: v21 1 0,  Up: History<2>

9.218 v21.0.0
=============

02 May 2016

   * Removed ez_setup.py from Setuptools sdist.  The bootstrap script
     will be maintained in its own branch and should be generally be
     retrieved from its canonical location at
     ‘https://bootstrap.pypa.io/ez_setup.py’.


File: setuptools.info,  Node: v20 10 0,  Next: v20 9 0,  Prev: v21 0 0,  Up: History<2>

9.219 v20.10.0
==============

25 Apr 2016

   * #553(1): egg_info section is now generated in a deterministic
     order, matching the order generated by earlier versions of Python.
     Except on Python 2.6, order is preserved when existing settings are
     present.

   * #556(2): Update to Packaging 16.7(3), restoring support for
     deprecated ‘python_implmentation’ marker.

   * #555(4): Upload command now prompts for a password when uploading
     to PyPI (or other repository) if no password is present in .pypirc
     or in the keyring.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/553

   (2) https://github.com/pypa/setuptools/issues/556

   (3) https://github.com/pypa/packaging/blob/16.7/CHANGELOG.rst

   (4) https://github.com/pypa/setuptools/issues/555


File: setuptools.info,  Node: v20 9 0,  Next: v20 8 1,  Prev: v20 10 0,  Up: History<2>

9.220 v20.9.0
=============

16 Apr 2016

   * #548(1): Update certify version to 2016.2.28

   * #545(2): Safely handle deletion of non-zip eggs in rotate command.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/548

   (2) https://github.com/pypa/setuptools/issues/545


File: setuptools.info,  Node: v20 8 1,  Next: v20 8 0,  Prev: v20 9 0,  Up: History<2>

9.221 v20.8.1
=============

15 Apr 2016

   * Issue #544(1): Fix issue with extra environment marker processing
     in WorkingSet due to refactor in v20.7.0.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/544


File: setuptools.info,  Node: v20 8 0,  Next: v20 7 0,  Prev: v20 8 1,  Up: History<2>

9.222 v20.8.0
=============

15 Apr 2016

   * Issue #543(1): Re-release so that latest release doesn’t cause déjà
     vu with distribute and setuptools 0.7 in older environments.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/543


File: setuptools.info,  Node: v20 7 0,  Next: v20 6 8,  Prev: v20 8 0,  Up: History<2>

9.223 v20.7.0
=============

10 Apr 2016

   * Refactored extra environment marker processing in WorkingSet.

   * Issue #533(1): Fixed intermittent test failures.

   * Issue #536(2): In msvc9_support, trap additional exceptions that
     might occur when importing ‘distutils.msvc9compiler’ in mingw
     environments.

   * Issue #537(3): Provide better context when package metadata fails
     to decode in UTF-8.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/533

   (2) https://github.com/pypa/setuptools/issues/536

   (3) https://github.com/pypa/setuptools/issues/537


File: setuptools.info,  Node: v20 6 8,  Next: v20 6 7,  Prev: v20 7 0,  Up: History<2>

9.224 v20.6.8
=============

09 May 2016

   * Issue #523(1): Restored support for environment markers, now
     honoring ‘extra’ environment markers.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/523


File: setuptools.info,  Node: v20 6 7,  Next: v20 6 6,  Prev: v20 6 8,  Up: History<2>

9.225 v20.6.7
=============

31 Mar 2016

   * Issue #523(1): Disabled support for environment markers introduced
     in v20.5.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/523


File: setuptools.info,  Node: v20 6 6,  Next: v20 6 0,  Prev: v20 6 7,  Up: History<2>

9.226 v20.6.6
=============

30 Mar 2016

   * Issue #503(1): Restore support for PEP 345(2) environment markers
     by updating to Packaging 16.6(3).

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/503

   (2) https://www.python.org/dev/peps/pep-0345/

   (3) https://github.com/pypa/packaging/blob/16.6/CHANGELOG.rst


File: setuptools.info,  Node: v20 6 0,  Next: 20 5,  Prev: v20 6 6,  Up: History<2>

9.227 v20.6.0
=============

29 Mar 2016

   * New release process that relies on bumpversion(1) and Travis CI for
     continuous deployment.

   * Project versioning semantics now follow semver(2) precisely.  The
     ‘v’ prefix on version numbers now also allows version numbers to be
     referenced in the changelog, e.g.
     ‘http://setuptools.readthedocs.io/en/latest/history.html#v20-6-0’.

   ---------- Footnotes ----------

   (1) https://github.com/peritus/bumpversion

   (2) https://semver.org


File: setuptools.info,  Node: 20 5,  Next: 20 4,  Prev: v20 6 0,  Up: History<2>

9.228 20.5
==========

29 Mar 2016

   * BB Pull Request #185(1), #470(2): Add support for environment
     markers in requirements in install_requires, setup_requires,
     tests_require as well as adding a test for the existing
     extra_requires machinery.

   ---------- Footnotes ----------

   (1) https://bitbucket.org/pypa/setuptools/pull-request/185

   (2) https://github.com/pypa/setuptools/issues/470


File: setuptools.info,  Node: 20 4,  Next: 20 3 1,  Prev: 20 5,  Up: History<2>

9.229 20.4
==========

29 Mar 2016

   * Issue #422(1): Moved hosting to Github(2) from Bitbucket(3).
     Issues have been migrated, though all issues and comments are
     attributed to bb-migration.  So if you have a particular issue or
     issues to which you’ve been subscribed, you will want to “watch”
     the equivalent issue in Github.  The Bitbucket project will be
     retained for the indefinite future, but Github now hosts the
     canonical project repository.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/422

   (2) https://github.com/pypa/setuptools

   (3) https://bitbucket.org/pypa/setuptools


File: setuptools.info,  Node: 20 3 1,  Next: 20 3,  Prev: 20 4,  Up: History<2>

9.230 20.3.1
============

18 Mar 2016

   * Issue #519(1): Remove import hook when reloading the
     ‘pkg_resources’ module.

   * BB Pull Request #184(2): Update documentation in ‘pkg_resources’
     around new ‘Requirement’ implementation.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/519

   (2) https://bitbucket.org/pypa/setuptools/pull-request/184


File: setuptools.info,  Node: 20 3,  Next: 20 2 2,  Prev: 20 3 1,  Up: History<2>

9.231 20.3
==========

15 Mar 2016

   * BB Pull Request #179(1): ‘pkg_resources.Requirement’ objects are
     now a subclass of ‘packaging.requirements.Requirement’, allowing
     any environment markers and url (if any) to be affiliated with the
     requirement

   * BB Pull Request #179(2): Restore use of RequirementParseError
     exception unintentionally dropped in 20.2.

   ---------- Footnotes ----------

   (1) https://bitbucket.org/pypa/setuptools/pull-request/179

   (2) https://bitbucket.org/pypa/setuptools/pull-request/179


File: setuptools.info,  Node: 20 2 2,  Next: 20 2 1,  Prev: 20 3,  Up: History<2>

9.232 20.2.2
============

27 Feb 2016

   * Issue #502(1): Correct regression in parsing of multiple version
     specifiers separated by commas and spaces.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/502


File: setuptools.info,  Node: 20 2 1,  Next: 20 2,  Prev: 20 2 2,  Up: History<2>

9.233 20.2.1
============

24 Feb 2016

   * Issue #499(1): Restore compatibility for legacy versions by bumping
     to packaging 16.4(2).

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/499

   (2) https://github.com/pypa/packaging/blob/16.4/CHANGELOG.rst


File: setuptools.info,  Node: 20 2,  Next: 20 1 1,  Prev: 20 2 1,  Up: History<2>

9.234 20.2
==========

19 Feb 2016

   * Changelog now includes release dates and links to PEPs.

   * BB Pull Request #173(1): Replace dual PEP 345(2) _markerlib
     implementation and PEP 426(3) implementation of environment marker
     support from packaging 16.1(4) and PEP 508(5).  Fixes Issue
     #122(6).  See also BB Pull Request #175(7), BB Pull Request
     #168(8), and BB Pull Request #164(9).  Additionally:

             - ‘Requirement.parse’ no longer retains the order of
               extras.

             - ‘parse_requirements’ now requires that all versions be
               PEP-440(10) compliant, as revealed in #499(11).  Packages
               released with invalid local versions should be
               re-released using the proper local version syntax, e.g.
               ‘mypkg-1.0+myorg.1’.

   ---------- Footnotes ----------

   (1) https://bitbucket.org/pypa/setuptools/pull-request/173

   (2) https://www.python.org/dev/peps/pep-0345/

   (3) https://www.python.org/dev/peps/pep-0426/

   (4) https://github.com/pypa/packaging/blob/16.1/CHANGELOG.rst

   (5) https://www.python.org/dev/peps/pep-0508/

   (6) https://github.com/pypa/setuptools/issues/122

   (7) https://bitbucket.org/pypa/setuptools/pull-request/175

   (8) https://bitbucket.org/pypa/setuptools/pull-request/168

   (9) https://bitbucket.org/pypa/setuptools/pull-request/164

   (10) https://www.python.org/dev/peps/pep-0440/

   (11) https://github.com/pypa/setuptools/issues/499


File: setuptools.info,  Node: 20 1 1,  Next: 20 1,  Prev: 20 2,  Up: History<2>

9.235 20.1.1
============

12 Feb 2016

   * Update ‘upload_docs’ command to also honor keyring for password
     resolution.


File: setuptools.info,  Node: 20 1,  Next: 20 0,  Prev: 20 1 1,  Up: History<2>

9.236 20.1
==========

11 Feb 2016

   * Added support for using passwords from keyring in the upload
     command.  See the upload docs(1) for details.

   ---------- Footnotes ----------

   (1) 
https://setuptools.readthedocs.io/en/latest/setuptools.html#upload-upload-source-and-or-egg-distributions-to-pypi


File: setuptools.info,  Node: 20 0,  Next: 19 7,  Prev: 20 1,  Up: History<2>

9.237 20.0
==========

07 Feb 2016

   * Issue #118(1): Once again omit the package metadata (egg-info) from
     the list of outputs in ‘--record’.  This version of setuptools can
     no longer be used to upgrade pip earlier than 6.0.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/118


File: setuptools.info,  Node: 19 7,  Next: 19 6 2,  Prev: 20 0,  Up: History<2>

9.238 19.7
==========

03 Feb 2016

   * Off-project PR: 0dcee79(1) and f9bd9b9(2) For FreeBSD, also honor
     root certificates from ca_root_nss(3).

   ---------- Footnotes ----------

   (1) 
https://github.com/pypa/setuptools/commit/0dcee791dfdcfacddaaec79b29f30a347a147413

   (2) 
https://github.com/pypa/setuptools/commit/f9bd9b9f5df54ef5a0bf8d16c3a889ab8c640580

   (3) 
https://github.com/pypa/setuptools/commit/3ae46c30225eb46e1f5aada1a19e88b79f04dc72


File: setuptools.info,  Node: 19 6 2,  Next: 19 6 1,  Prev: 19 7,  Up: History<2>

9.239 19.6.2
============

31 Jan 2016

   * Issue #491(1): Correct regression incurred in 19.4 where a
     double-namespace package installed using pip would cause a
     TypeError.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/491


File: setuptools.info,  Node: 19 6 1,  Next: 19 6,  Prev: 19 6 2,  Up: History<2>

9.240 19.6.1
============

29 Jan 2016

   * Restore compatibility for PyPy 3 compatibility lost in 19.4.1
     addressing Issue #487(1).

   * ‘setuptools.launch’ shim now loads scripts in a new namespace,
     avoiding getting relative imports from the setuptools package on
     Python 2.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/487


File: setuptools.info,  Node: 19 6,  Next: 19 5,  Prev: 19 6 1,  Up: History<2>

9.241 19.6
==========

24 Jan 2016

   * Added a new entry script ‘setuptools.launch’, implementing the shim
     found in ‘pip.util.setuptools_build’.  Use this command to launch
     distutils-only packages under setuptools in the same way that pip
     does, causing the setuptools monkeypatching of distutils to be
     invoked prior to invoking a script.  Useful for debugging or
     otherwise installing a distutils-only package under setuptools when
     pip isn’t available or otherwise does not expose the desired
     functionality.  For example:

          $ python -m setuptools.launch setup.py develop

   * Issue #488(1): Fix dual manifestation of Extension class in
     extension packages installed as dependencies when Cython is
     present.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/488


File: setuptools.info,  Node: 19 5,  Next: 19 4 1,  Prev: 19 6,  Up: History<2>

9.242 19.5
==========

23 Jan 2016

   * Issue #486(1): Correct TypeError when getfilesystemencoding returns
     None.

   * Issue #139(2): Clarified the license as MIT.

   * BB Pull Request #169(3): Removed special handling of command spec
     in scripts for Jython.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/486

   (2) https://github.com/pypa/setuptools/issues/139

   (3) https://bitbucket.org/pypa/setuptools/pull-request/169


File: setuptools.info,  Node: 19 4 1,  Next: 19 4,  Prev: 19 5,  Up: History<2>

9.243 19.4.1
============

23 Jan 2016

   * Issue #487(1): Use direct invocation of ‘importlib.machinery’ in
     ‘pkg_resources’ to avoid missing detection on relevant platforms.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/487


File: setuptools.info,  Node: 19 4,  Next: 19 3,  Prev: 19 4 1,  Up: History<2>

9.244 19.4
==========

16 Jan 2016

   * Issue #341(1): Correct error in path handling of package data files
     in ‘build_py’ command when package is empty.

   * Distribute #323(2), Issue #141(3), Issue #207(4), and BB Pull
     Request #167(5): Another implementation of
     ‘pkg_resources.WorkingSet’ and ‘pkg_resources.Distribution’ that
     supports replacing an extant package with a new one, allowing for
     setup_requires dependencies to supersede installed packages for the
     session.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/341

   (2) https://bitbucket.org/tarek/distribute/issue/323

   (3) https://github.com/pypa/setuptools/issues/141

   (4) https://github.com/pypa/setuptools/issues/207

   (5) https://bitbucket.org/pypa/setuptools/pull-request/167


File: setuptools.info,  Node: 19 3,  Next: 19 2,  Prev: 19 4,  Up: History<2>

9.245 19.3
==========

06 Jan 2016

   * Issue #229(1): Implement new technique for readily incorporating
     dependencies conditionally from vendored copies or primary
     locations.  Adds a new dependency on six.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/229


File: setuptools.info,  Node: 19 2,  Next: 19 1 1,  Prev: 19 3,  Up: History<2>

9.246 19.2
==========

25 Dec 2015

   * BB Pull Request #163(1): Add get_command_list method to
     Distribution.

   * BB Pull Request #162(2): Add missing whitespace to multiline string
     literals.

   ---------- Footnotes ----------

   (1) https://bitbucket.org/pypa/setuptools/pull-request/163

   (2) https://bitbucket.org/pypa/setuptools/pull-request/162


File: setuptools.info,  Node: 19 1 1,  Next: 19 1,  Prev: 19 2,  Up: History<2>

9.247 19.1.1
============

16 Dec 2015

   * Issue #476(1): Cast version to string (using default encoding) to
     avoid creating Unicode types on Python 2 clients.

   * Issue #477(2): In Powershell downloader, use explicit rendering of
     strings, rather than rely on ‘repr’, which can be incorrect
     (especially on Python 2).

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/476

   (2) https://github.com/pypa/setuptools/issues/477


File: setuptools.info,  Node: 19 1,  Next: 19 0,  Prev: 19 1 1,  Up: History<2>

9.248 19.1
==========

16 Dec 2015

   * Issue #215(1): The bootstrap script ‘ez_setup.py’ now automatically
     detects the latest version of setuptools (using PyPI JSON API)
     rather than hard-coding a particular value.

   * Issue #475(2): Fix incorrect usage in _translate_metadata2.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/215

   (2) https://github.com/pypa/setuptools/issues/475


File: setuptools.info,  Node: 19 0,  Next: 18 8 1,  Prev: 19 1,  Up: History<2>

9.249 19.0
==========

15 Dec 2015

   * Issue #442(1): Use RawConfigParser for parsing .pypirc file.
     Interpolated values are no longer honored in .pypirc files.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/442


File: setuptools.info,  Node: 18 8 1,  Next: 18 8,  Prev: 19 0,  Up: History<2>

9.250 18.8.1
============

13 Dec 2015

   * Issue #440(1): Prevent infinite recursion when a SandboxViolation
     or other UnpickleableException occurs in a sandbox context with
     setuptools hidden.  Fixes regression introduced in Setuptools 12.0.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/440


File: setuptools.info,  Node: 18 8,  Next: 18 7 1,  Prev: 18 8 1,  Up: History<2>

9.251 18.8
==========

11 Dec 2015

   * Deprecated ‘egg_info.get_pkg_info_revision’.

   * Issue #471(1): Don’t rely on repr for an HTML attribute value in
     package_index.

   * Issue #419(2): Avoid errors in FileMetadata when the metadata
     directory is broken.

   * Issue #472(3): Remove deprecated use of ‘U’ in mode parameter when
     opening files.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/471

   (2) https://github.com/pypa/setuptools/issues/419

   (3) https://github.com/pypa/setuptools/issues/472


File: setuptools.info,  Node: 18 7 1,  Next: 18 7,  Prev: 18 8,  Up: History<2>

9.252 18.7.1
============

01 Dec 2015

   * Issue #469(1): Refactored logic for Issue #419(2) fix to re-use
     metadata loading from Provider.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/469

   (2) https://github.com/pypa/setuptools/issues/419


File: setuptools.info,  Node: 18 7,  Next: 18 6 1,  Prev: 18 7 1,  Up: History<2>

9.253 18.7
==========

28 Nov 2015

   * Update dependency on certify.

   * BB Pull Request #160(1): Improve detection of gui script in
     ‘easy_install._adjust_header’.

   * Made ‘test.test_args’ a non-data property; alternate fix for the
     issue reported in BB Pull Request #155(2).

   * Issue #453(3): In ‘ez_setup’ bootstrap module, unload all
     ‘pkg_resources’ modules following download.

   * BB Pull Request #158(4): Honor PEP-488(5) when excluding files for
     namespace packages.

   * Issue #419(6) and BB Pull Request #144(7): Add experimental support
     for reading the version info from distutils-installed metadata
     rather than using the version in the filename.

   ---------- Footnotes ----------

   (1) https://bitbucket.org/pypa/setuptools/pull-request/160

   (2) https://bitbucket.org/pypa/setuptools/pull-request/155

   (3) https://github.com/pypa/setuptools/issues/453

   (4) https://bitbucket.org/pypa/setuptools/pull-request/158

   (5) https://www.python.org/dev/peps/pep-0488/

   (6) https://github.com/pypa/setuptools/issues/419

   (7) https://bitbucket.org/pypa/setuptools/pull-request/144


File: setuptools.info,  Node: 18 6 1,  Next: 18 6,  Prev: 18 7,  Up: History<2>

9.254 18.6.1
============

24 Nov 2015

   * Issue #464(1): Correct regression in invocation of superclass on
     old-style class on Python 2.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/464


File: setuptools.info,  Node: 18 6,  Next: 18 5,  Prev: 18 6 1,  Up: History<2>

9.255 18.6
==========

24 Nov 2015

   * Issue #439(1): When installing entry_point scripts under
     development, omit the version number of the package, allowing any
     version of the package to be used.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/439


File: setuptools.info,  Node: 18 5,  Next: 18 4,  Prev: 18 6,  Up: History<2>

9.256 18.5
==========

01 Nov 2015

   * In preparation for dropping support for Python 3.2, a warning is
     now logged when pkg_resources is imported on Python 3.2 or earlier
     Python 3 versions.

   * Add support for python_platform_implementation environment
     marker(1).

   * Fix dictionary mutation during iteration(2).

   ---------- Footnotes ----------

   (1) 
https://github.com/pypa/setuptools/commit/94416707fd59a65f4a8f7f70541d6b3fc018b626

   (2) 
https://github.com/pypa/setuptools/commit/57ebfa41e0f96b97e599ecd931b7ae8a143e096e


File: setuptools.info,  Node: 18 4,  Next: 18 3 2,  Prev: 18 5,  Up: History<2>

9.257 18.4
==========

10 Oct 2015

   * Issue #446(1): Test command now always invokes unittest, even if no
     test suite is supplied.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/446


File: setuptools.info,  Node: 18 3 2,  Next: 18 3 1,  Prev: 18 4,  Up: History<2>

9.258 18.3.2
============

19 Sep 2015

   * Correct another regression in setuptools.findall where the fix for
     Python #12885(1) was lost.

   ---------- Footnotes ----------

   (1) http://bugs.python.org/issue12885


File: setuptools.info,  Node: 18 3 1,  Next: 18 3,  Prev: 18 3 2,  Up: History<2>

9.259 18.3.1
============

07 Sep 2015

   * Issue #425(1): Correct regression in setuptools.findall.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/425


File: setuptools.info,  Node: 18 3,  Next: 18 2,  Prev: 18 3 1,  Up: History<2>

9.260 18.3
==========

06 Sep 2015

   * BB Pull Request #135(1): Setuptools now allows disabling of the
     manipulation of the sys.path during the processing of the
     easy-install.pth file.  To do so, set the environment variable
     ‘SETUPTOOLS_SYS_PATH_TECHNIQUE’ to anything but “rewrite” (consider
     “raw”).  During any install operation with manipulation disabled,
     setuptools packages will be appended to sys.path naturally.

     Future versions may change the default behavior to disable
     manipulation.  If so, the default behavior can be retained by
     setting the variable to “rewrite”.

   * Issue #257(2): ‘easy_install --version’ now shows more detail about
     the installation location and Python version.

   * Refactor setuptools.findall in preparation for re-submission back
     to distutils.

   ---------- Footnotes ----------

   (1) https://bitbucket.org/pypa/setuptools/pull-request/135

   (2) https://github.com/pypa/setuptools/issues/257


File: setuptools.info,  Node: 18 2,  Next: 18 1,  Prev: 18 3,  Up: History<2>

9.261 18.2
==========

19 Aug 2015

   * Issue #412(1): More efficient directory search in ‘find_packages’.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/412


File: setuptools.info,  Node: 18 1,  Next: 18 0 1,  Prev: 18 2,  Up: History<2>

9.262 18.1
==========

02 Aug 2015

   * Upgrade to vendored packaging 15.3(1).

   ---------- Footnotes ----------

   (1) https://github.com/pypa/packaging/blob/15.3/CHANGELOG.rst


File: setuptools.info,  Node: 18 0 1,  Next: 18 0,  Prev: 18 1,  Up: History<2>

9.263 18.0.1
============

24 Jun 2015

   * Issue #401(1): Fix failure in test suite.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/401


File: setuptools.info,  Node: 18 0,  Next: 17 1 1,  Prev: 18 0 1,  Up: History<2>

9.264 18.0
==========

13 Jun 2015

   * Dropped support for builds with Pyrex.  Only Cython is supported.

   * Issue #288(1): Detect Cython later in the build process, after
     ‘setup_requires’ dependencies are resolved.  Projects backed by
     Cython can now be readily built with a ‘setup_requires’ dependency.
     For example:

          ext = setuptools.Extension('mylib', ['src/CythonStuff.pyx', 'src/CStuff.c'])
          setuptools.setup(
              ...
              ext_modules=[ext],
              setup_requires=['cython'],
          )

     For compatibility with older versions of setuptools, packagers
     should still include ‘src/CythonMod.c’ in the source distributions
     or require that Cython be present before building source
     distributions.  However, for systems with this build of setuptools,
     Cython will be downloaded on demand.

   * Issue #396(2): Fixed test failure on OS X.

   * BB Pull Request #136(3): Remove excessive quoting from shebang
     headers for Jython.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/288

   (2) https://github.com/pypa/setuptools/issues/396

   (3) https://bitbucket.org/pypa/setuptools/pull-request/136


File: setuptools.info,  Node: 17 1 1,  Next: 17 1,  Prev: 18 0,  Up: History<2>

9.265 17.1.1
============

08 Jun 2015

   * Backed out unintended changes to pkg_resources, restoring removal
     of deprecated imp module (ref(1)).

   ---------- Footnotes ----------

   (1) 
https://bitbucket.org/pypa/setuptools/commits/f572ec9563d647fa8d4ffc534f2af8070ea07a8b#comment-1881283


File: setuptools.info,  Node: 17 1,  Next: 17 0,  Prev: 17 1 1,  Up: History<2>

9.266 17.1
==========

07 Jun 2015

   * Issue #380(1): Add support for range operators on environment
     marker evaluation.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/380


File: setuptools.info,  Node: 17 0,  Next: 16 0,  Prev: 17 1,  Up: History<2>

9.267 17.0
==========

28 May 2015

   * Issue #378(1): Do not use internal importlib._bootstrap module.

   * Issue #390(2): Disallow console scripts with path separators in the
     name.  Removes unintended functionality and brings behavior into
     parity with pip.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/378

   (2) https://github.com/pypa/setuptools/issues/390


File: setuptools.info,  Node: 16 0,  Next: 15 2,  Prev: 17 0,  Up: History<2>

9.268 16.0
==========

18 May 2015

   * BB Pull Request #130(1): Better error messages for errors in parsed
     requirements.

   * BB Pull Request #133(2): Removed ‘setuptools.tests’ from the
     installed packages.

   * BB Pull Request #129(3): Address deprecation warning due to usage
     of imp module.

   ---------- Footnotes ----------

   (1) https://bitbucket.org/pypa/setuptools/pull-request/130

   (2) https://bitbucket.org/pypa/setuptools/pull-request/133

   (3) https://bitbucket.org/pypa/setuptools/pull-request/129


File: setuptools.info,  Node: 15 2,  Next: 15 1,  Prev: 16 0,  Up: History<2>

9.269 15.2
==========

26 Apr 2015

   * Issue #373(1): Provisionally expose
     ‘pkg_resources._initialize_master_working_set’, allowing for
     imperative re-initialization of the master working set.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/373


File: setuptools.info,  Node: 15 1,  Next: 15 0,  Prev: 15 2,  Up: History<2>

9.270 15.1
==========

15 Apr 2015

   * Updated to Packaging 15.1(1) to address Packaging #28(2).

   * Fix ‘setuptools.sandbox._execfile()’ with Python 3.1.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/packaging/blob/15.1/CHANGELOG.rst

   (2) https://github.com/pypa/packaging/issues/28


File: setuptools.info,  Node: 15 0,  Next: 14 3 1,  Prev: 15 1,  Up: History<2>

9.271 15.0
==========

03 Apr 2015

   * BB Pull Request #126(1): DistributionNotFound message now lists the
     package or packages that required it.  E.g.:

          pkg_resources.DistributionNotFound: The 'colorama>=0.3.1' distribution was not found and is required by smlib.log.

     Note that zc.buildout once dependended on the string rendering of
     this message to determine the package that was not found.  This
     expectation has since been changed, but older versions of buildout
     may experience problems.  See Buildout #242(2) for details.

   ---------- Footnotes ----------

   (1) https://bitbucket.org/pypa/setuptools/pull-request/126

   (2) https://github.com/buildout/buildout/issues/242


File: setuptools.info,  Node: 14 3 1,  Next: 14 3,  Prev: 15 0,  Up: History<2>

9.272 14.3.1
============

20 Mar 2015

   * Issue #307(1): Removed PEP-440(2) warning during parsing of
     versions in ‘pkg_resources.Distribution’.

   * Issue #364(3): Replace deprecated usage with recommended usage of
     ‘EntryPoint.load’.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/307

   (2) https://www.python.org/dev/peps/pep-0440/

   (3) https://github.com/pypa/setuptools/issues/364


File: setuptools.info,  Node: 14 3,  Next: 14 2,  Prev: 14 3 1,  Up: History<2>

9.273 14.3
==========

15 Mar 2015

   * Issue #254(1): When creating temporary egg cache on Unix, use mode
     755 for creating the directory to avoid the subsequent warning if
     the directory is group writable.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/254


File: setuptools.info,  Node: 14 2,  Next: 14 1 1,  Prev: 14 3,  Up: History<2>

9.274 14.2
==========

15 Mar 2015

   * Issue #137(1): Update ‘Distribution.hashcmp’ so that Distributions
     with None for pyversion or platform can be compared against
     Distributions defining those attributes.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/137


File: setuptools.info,  Node: 14 1 1,  Next: 14 1,  Prev: 14 2,  Up: History<2>

9.275 14.1.1
============

14 Mar 2015

   * Issue #360(1): Removed undesirable behavior from test runs,
     preventing write tests and installation to system site packages.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/360


File: setuptools.info,  Node: 14 1,  Next: 14 0,  Prev: 14 1 1,  Up: History<2>

9.276 14.1
==========

14 Mar 2015

   * BB Pull Request #125(1): Add ‘__ne__’ to Requirement class.

   * Various refactoring of easy_install.

   ---------- Footnotes ----------

   (1) https://bitbucket.org/pypa/setuptools/pull-request/125


File: setuptools.info,  Node: 14 0,  Next: 13 0 2,  Prev: 14 1,  Up: History<2>

9.277 14.0
==========

06 Mar 2015

   * Bootstrap script now accepts ‘--to-dir’ to customize save directory
     or allow for re-use of existing repository of setuptools versions.
     See BB Pull Request #112(1) for background.

   * Issue #285(2): ‘easy_install’ no longer will default to installing
     packages to the “user site packages” directory if it is itself
     installed there.  Instead, the user must pass ‘--user’ in all cases
     to install packages to the user site packages.  This behavior now
     matches that of “pip install”.  To configure an environment to
     always install to the user site packages, consider using the
     “install-dir” and “scripts-dir” parameters to easy_install through
     an appropriate distutils config file.

   ---------- Footnotes ----------

   (1) https://bitbucket.org/pypa/setuptools/pull-request/112

   (2) https://github.com/pypa/setuptools/issues/285


File: setuptools.info,  Node: 13 0 2,  Next: 13 0 1,  Prev: 14 0,  Up: History<2>

9.278 13.0.2
============

06 Mar 2015

   * Issue #359(1): Include pytest.ini in the sdist so invocation of
     py.test on the sdist honors the pytest configuration.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/359


File: setuptools.info,  Node: 13 0 1,  Next: 13 0,  Prev: 13 0 2,  Up: History<2>

9.279 13.0.1
============

05 Mar 2015

Re-release of 13.0.  Intermittent connectivity issues caused the release
process to fail and PyPI uploads no longer accept files for 13.0.


File: setuptools.info,  Node: 13 0,  Next: 12 4,  Prev: 13 0 1,  Up: History<2>

9.280 13.0
==========

05 Mar 2015

   * Issue #356(1): Back out BB Pull Request #119(2) as it requires
     Setuptools 10 or later as the source during an upgrade.

   * Removed build_py class from setup.py.  According to 892f439d216e,
     this functionality was added to support upgrades from old
     Distribute versions, 0.6.5 and 0.6.6.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/356

   (2) https://bitbucket.org/pypa/setuptools/pull-request/119


File: setuptools.info,  Node: 12 4,  Next: 12 3,  Prev: 13 0,  Up: History<2>

9.281 12.4
==========

04 Mar 2015

   * BB Pull Request #119(1): Restore writing of ‘setup_requires’ to
     metadata (previously added in 8.4 and removed in 9.0).

   ---------- Footnotes ----------

   (1) https://bitbucket.org/pypa/setuptools/pull-request/119


File: setuptools.info,  Node: 12 3,  Next: 12 2,  Prev: 12 4,  Up: History<2>

9.282 12.3
==========

26 Feb 2015

   * Documentation is now linked using the rst.linker package.

   * Fix ‘setuptools.command.easy_install.extract_wininst_cfg()’ with
     Python 2.6 and 2.7.

   * Issue #354(1).  Added documentation on building setuptools
     documentation.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/354


File: setuptools.info,  Node: 12 2,  Next: 12 1,  Prev: 12 3,  Up: History<2>

9.283 12.2
==========

16 Feb 2015

   * Issue #345(1): Unload all modules under pkg_resources during
     ‘ez_setup.use_setuptools()’.

   * Issue #336(2): Removed deprecation from ‘ez_setup.use_setuptools’,
     as it is clearly still used by buildout’s bootstrap.  ‘ez_setup’
     remains deprecated for use by individual packages.

   * Simplified implementation of ‘ez_setup.use_setuptools’.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/345

   (2) https://github.com/pypa/setuptools/issues/336


File: setuptools.info,  Node: 12 1,  Next: 12 0 5,  Prev: 12 2,  Up: History<2>

9.284 12.1
==========

10 Feb 2015

   * BB Pull Request #118(1): Soften warning for non-normalized versions
     in Distribution.

   ---------- Footnotes ----------

   (1) https://bitbucket.org/pypa/setuptools/pull-request/118


File: setuptools.info,  Node: 12 0 5,  Next: 12 0 4,  Prev: 12 1,  Up: History<2>

9.285 12.0.5
============

26 Jan 2015

   * Issue #339(1): Correct Attribute reference in
     ‘cant_write_to_target’.

   * Issue #336(2): Deprecated ‘ez_setup.use_setuptools’.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/339

   (2) https://github.com/pypa/setuptools/issues/336


File: setuptools.info,  Node: 12 0 4,  Next: 12 0 3,  Prev: 12 0 5,  Up: History<2>

9.286 12.0.4
============

20 Jan 2015

   * Issue #335(1): Fix script header generation on Windows.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/335


File: setuptools.info,  Node: 12 0 3,  Next: 12 0 2,  Prev: 12 0 4,  Up: History<2>

9.287 12.0.3
============

18 Jan 2015

   * Fixed incorrect class attribute in ‘install_scripts’.  Tests would
     be nice.


File: setuptools.info,  Node: 12 0 2,  Next: 12 0 1,  Prev: 12 0 3,  Up: History<2>

9.288 12.0.2
============

18 Jan 2015

   * Issue #331(1): Fixed ‘install_scripts’ command on Windows systems
     corrupting the header.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/331


File: setuptools.info,  Node: 12 0 1,  Next: 12 0,  Prev: 12 0 2,  Up: History<2>

9.289 12.0.1
============

16 Jan 2015

   * Restore ‘setuptools.command.easy_install.sys_executable’ for pbr
     compatibility.  For the future, tools should construct a
     CommandSpec explicitly.


File: setuptools.info,  Node: 12 0,  Next: 11 3 1,  Prev: 12 0 1,  Up: History<2>

9.290 12.0
==========

16 Jan 2015

   * Issue #188(1): Setuptools now support multiple entities in the
     value for ‘build.executable’, such that an executable of
     “/usr/bin/env my-python” may be specified.  This means that systems
     with a specified executable whose name has spaces in the path must
     be updated to escape or quote that value.

   * Deprecated ‘easy_install.ScriptWriter.get_writer’, replaced by
     ‘.best()’ with slightly different semantics (no force_windows
     flag).

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/188


File: setuptools.info,  Node: 11 3 1,  Next: 11 3,  Prev: 12 0,  Up: History<2>

9.291 11.3.1
============

06 Jan 2015

   * Issue #327(1): Formalize and restore support for any printable
     character in an entry point name.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/327


File: setuptools.info,  Node: 11 3,  Next: 11 2,  Prev: 11 3 1,  Up: History<2>

9.292 11.3
==========

05 Jan 2015

   * Expose ‘EntryPoint.resolve’ in place of EntryPoint._load,
     implementing the simple, non-requiring load.  Deprecated all uses
     of ‘EntryPoint._load’ except for calling with no parameters, which
     is just a shortcut for ‘ep.require(); ep.resolve();’.

     Apps currently invoking ‘ep.load(require=False)’ should instead do
     the following if wanting to avoid the deprecating warning:

          getattr(ep, "resolve", lambda: ep.load(require=False))()


File: setuptools.info,  Node: 11 2,  Next: 11 1,  Prev: 11 3,  Up: History<2>

9.293 11.2
==========

05 Jan 2015

   * Pip #2326(1): Report deprecation warning at stacklevel 2 for easier
     diagnosis.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/pip/issues/2326


File: setuptools.info,  Node: 11 1,  Next: 11 0,  Prev: 11 2,  Up: History<2>

9.294 11.1
==========

04 Jan 2015

   * Issue #281(1): Since Setuptools 6.1 (Issue #268(2)), a ValueError
     would be raised in certain cases where VersionConflict was raised
     with two arguments, which occurred in
     ‘pkg_resources.WorkingSet.find’.  This release adds support for
     indicating the dependent packages while maintaining support for a
     VersionConflict when no dependent package context is known.  New
     unit tests now capture the expected interface.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/281

   (2) https://github.com/pypa/setuptools/issues/268


File: setuptools.info,  Node: 11 0,  Next: 10 2 1,  Prev: 11 1,  Up: History<2>

9.295 11.0
==========

02 Jan 2015

   * Interop #3(1): Upgrade to Packaging 15.0(2); updates to PEP 440(3)
     so that >1.7 does not exclude 1.7.1 but does exclude 1.7.0 and
     1.7.0.post1.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/interoperability-peps/issues/3

   (2) https://github.com/pypa/packaging/blob/15.0/CHANGELOG.rst

   (3) https://www.python.org/dev/peps/pep-0440/


File: setuptools.info,  Node: 10 2 1,  Next: 10 2,  Prev: 11 0,  Up: History<2>

9.296 10.2.1
============

02 Jan 2015

   * Issue #323(1): Fix regression in entry point name parsing.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/323


File: setuptools.info,  Node: 10 2,  Next: 10 1,  Prev: 10 2 1,  Up: History<2>

9.297 10.2
==========

02 Jan 2015

   * Deprecated use of EntryPoint.load(require=False).  Passing a
     boolean to a function to select behavior is an anti-pattern.
     Instead use ‘Entrypoint._load()’.

   * Substantial refactoring of all unit tests.  Tests are now much
     leaner and re-use a lot of fixtures and contexts for better clarity
     of purpose.


File: setuptools.info,  Node: 10 1,  Next: 10 0 1,  Prev: 10 2,  Up: History<2>

9.298 10.1
==========

31 Dec 2014

   * Issue #320(1): Added a compatibility implementation of
     ‘sdist._default_revctrl’ so that systems relying on that interface
     do not fail (namely, Ubuntu 12.04 and similar Debian releases).

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/320


File: setuptools.info,  Node: 10 0 1,  Next: 10 0,  Prev: 10 1,  Up: History<2>

9.299 10.0.1
============

30 Dec 2014

   * Issue #319(1): Fixed issue installing pure distutils packages.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/319


File: setuptools.info,  Node: 10 0,  Next: 9 1,  Prev: 10 0 1,  Up: History<2>

9.300 10.0
==========

30 Dec 2014

   * Issue #313(1): Removed built-in support for subversion.  Projects
     wishing to retain support for subversion will need to use a third
     party library.  The extant implementation is being ported to
     setuptools_svn(2).

   * Issue #315(3): Updated setuptools to hide its own loaded modules
     during installation of another package.  This change will enable
     setuptools to upgrade (or downgrade) itself even when its own
     metadata and implementation change.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/313

   (2) https://pypi.org/project/setuptools_svn/

   (3) https://github.com/pypa/setuptools/issues/315


File: setuptools.info,  Node: 9 1,  Next: 9 0 1,  Prev: 10 0,  Up: History<2>

9.301 9.1
=========

29 Dec 2014

   * Prefer vendored packaging library as recommended(1).

   ---------- Footnotes ----------

   (1) 
https://github.com/pypa/setuptools/commit/170657b68f4b92e7e1bf82f5e19a831f5744af67


File: setuptools.info,  Node: 9 0 1,  Next: 9 0,  Prev: 9 1,  Up: History<2>

9.302 9.0.1
===========

29 Dec 2014

   * Issue #312(1): Restored presence of pkg_resources API tests
     (doctest) to sdist.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/312


File: setuptools.info,  Node: 9 0,  Next: 8 4,  Prev: 9 0 1,  Up: History<2>

9.303 9.0
=========

28 Dec 2014

   * Issue #314(1): Disabled support for ‘setup_requires’ metadata to
     avoid issue where Setuptools was unable to upgrade over earlier
     versions.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/314


File: setuptools.info,  Node: 8 4,  Next: 8 3,  Prev: 9 0,  Up: History<2>

9.304 8.4
=========

26 Dec 2014

   * BB Pull Request #106(1): Now write ‘setup_requires’ metadata.

   ---------- Footnotes ----------

   (1) https://bitbucket.org/pypa/setuptools/pull-request/106


File: setuptools.info,  Node: 8 3,  Next: 8 2 1,  Prev: 8 4,  Up: History<2>

9.305 8.3
=========

24 Dec 2014

   * Issue #311(1): Decoupled pkg_resources from setuptools once again.
     ‘pkg_resources’ is now a package instead of a module.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/311


File: setuptools.info,  Node: 8 2 1,  Next: 8 2,  Prev: 8 3,  Up: History<2>

9.306 8.2.1
===========

18 Dec 2014

   * Issue #306(1): Suppress warnings about Version format except in
     select scenarios (such as installation).

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/306


File: setuptools.info,  Node: 8 2,  Next: 8 1,  Prev: 8 2 1,  Up: History<2>

9.307 8.2
=========

18 Dec 2014

   * BB Pull Request #85(1): Search egg-base when adding egg-info to
     manifest.

   ---------- Footnotes ----------

   (1) https://bitbucket.org/pypa/setuptools/pull-request/85


File: setuptools.info,  Node: 8 1,  Next: 8 0 4,  Prev: 8 2,  Up: History<2>

9.308 8.1
=========

18 Dec 2014

   * Upgrade ‘packaging’ to 14.5, giving preference to “rc” as
     designator for release candidates over “c”.

   * PEP-440(1) warnings are now raised as their own class,
     ‘pkg_resources.PEP440Warning’, instead of RuntimeWarning.

   * Disabled warnings on empty versions.

   ---------- Footnotes ----------

   (1) https://www.python.org/dev/peps/pep-0440/


File: setuptools.info,  Node: 8 0 4,  Next: 8 0 3,  Prev: 8 1,  Up: History<2>

9.309 8.0.4
===========

15 Dec 2014

   * Upgrade ‘packaging’ to 14.4, fixing an error where there is a
     different result for if 2.0.5 is contained within >2.0dev and
     >2.0.dev even though normalization rules should have made them
     equal.

   * Issue #296(1): Add warning when a version is parsed as legacy.
     This warning will make it easier for developers to recognize
     deprecated version numbers.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/296


File: setuptools.info,  Node: 8 0 3,  Next: 8 0 2,  Prev: 8 0 4,  Up: History<2>

9.310 8.0.3
===========

15 Dec 2014

   * Issue #296(1): Restored support for ‘__hash__’ on parse_version
     results.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/296


File: setuptools.info,  Node: 8 0 2,  Next: 8 0 1,  Prev: 8 0 3,  Up: History<2>

9.311 8.0.2
===========

14 Dec 2014

   * Issue #296(1): Restored support for ‘__getitem__’ and sort
     operations on parse_version result.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/296


File: setuptools.info,  Node: 8 0 1,  Next: 8 0,  Prev: 8 0 2,  Up: History<2>

9.312 8.0.1
===========

13 Dec 2014

   * Issue #296(1): Restore support for iteration over parse_version
     result, but deprecated that usage with a warning.  Fixes failure
     with buildout.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/296


File: setuptools.info,  Node: 8 0,  Next: 7 0,  Prev: 8 0 1,  Up: History<2>

9.313 8.0
=========

13 Dec 2014

   * Implement PEP 440(1) within pkg_resources and setuptools.  This
     change deprecates some version numbers such that they will no
     longer be installable without using the ‘===’ escape hatch.  See
     the changes to test_resources(2) for specific examples of version
     numbers and specifiers that are no longer supported.  Setuptools
     now “vendors” the packaging(3) library.

   ---------- Footnotes ----------

   (1) https://www.python.org/dev/peps/pep-0440/

   (2) 
https://bitbucket.org/pypa/setuptools/commits/dcd552da643c4448056de84c73d56da6d70769d5#chg-setuptools/tests/test_resources.py

   (3) https://github.com/pypa/packaging


File: setuptools.info,  Node: 7 0,  Next: 6 1,  Prev: 8 0,  Up: History<2>

9.314 7.0
=========

19 Oct 2014

   * Issue #80(1), Issue #209(2): Eggs that are downloaded for
     ‘setup_requires’, ‘test_requires’, etc.  are now placed in a
     ‘./.eggs’ directory instead of directly in the current directory.
     This choice of location means the files can be readily managed
     (removed, ignored).  Additionally, later phases or invocations of
     setuptools will not detect the package as already installed and
     ignore it for permanent install (See #209(3)).

     This change is indicated as backward-incompatible as installations
     that depend on the installation in the current directory will need
     to account for the new location.  Systems that ignore ‘*.egg’ will
     probably need to be adapted to ignore ‘.eggs’.  The files will need
     to be manually moved or will be retrieved again.  Most use cases
     will require no attention.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/80

   (2) https://github.com/pypa/setuptools/issues/209

   (3) https://github.com/pypa/setuptools/issues/209


File: setuptools.info,  Node: 6 1,  Next: 6 0 2,  Prev: 7 0,  Up: History<2>

9.315 6.1
=========

11 Oct 2014

   * Issue #268(1): When resolving package versions, a VersionConflict
     now reports which package previously required the conflicting
     version.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/268


File: setuptools.info,  Node: 6 0 2,  Next: 6 0 1,  Prev: 6 1,  Up: History<2>

9.316 6.0.2
===========

29 Sep 2014

   * Issue #262(1): Fixed regression in pip install due to egg-info
     directories being omitted.  Re-opens Issue #118(2).

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/262

   (2) https://github.com/pypa/setuptools/issues/118


File: setuptools.info,  Node: 6 0 1,  Next: 6 0,  Prev: 6 0 2,  Up: History<2>

9.317 6.0.1
===========

27 Sep 2014

   * Issue #259(1): Fixed regression with namespace package handling on
     ‘single version, externally managed’ installs.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/259


File: setuptools.info,  Node: 6 0,  Next: 5 8,  Prev: 6 0 1,  Up: History<2>

9.318 6.0
=========

27 Sep 2014

   * Issue #100(1): When building a distribution, Setuptools will no
     longer match default files using platform-dependent case
     sensitivity, but rather will only match the files if their case
     matches exactly.  As a result, on Windows and other
     case-insensitive file systems, files with names such as
     ‘readme.txt’ or ‘README.TXT’ will be omitted from the distribution
     and a warning will be issued indicating that ‘README.txt’ was not
     found.  Other filenames affected are:

             - README.rst

             - README

             - setup.cfg

             - setup.py (or the script name)

             - test/test*.py

     Any users producing distributions with filenames that match those
     above case-insensitively, but not case-sensitively, should rename
     those files in their repository for better portability.

   * BB Pull Request #72(2): When using
     ‘single_version_externally_managed’, the exclusion list now
     includes Python 3.2 ‘__pycache__’ entries.

   * BB Pull Request #76(3) and BB Pull Request #78(4): lines in
     top_level.txt are now ordered deterministically.

   * Issue #118(5): The egg-info directory is now no longer included in
     the list of outputs.

   * Issue #258(6): Setuptools now patches distutils msvc9compiler to
     recognize the specially-packaged compiler package for easy
     extension module support on Python 2.6, 2.7, and 3.2.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/100

   (2) https://bitbucket.org/pypa/setuptools/pull-request/72

   (3) https://bitbucket.org/pypa/setuptools/pull-request/76

   (4) https://bitbucket.org/pypa/setuptools/pull-request/78

   (5) https://github.com/pypa/setuptools/issues/118

   (6) https://github.com/pypa/setuptools/issues/258


File: setuptools.info,  Node: 5 8,  Next: 5 7,  Prev: 6 0,  Up: History<2>

9.319 5.8
=========

18 Sep 2014

   * Issue #237(1): ‘pkg_resources’ now uses explicit detection of
     Python 2 vs.  Python 3, supporting environments where builtins have
     been patched to make Python 3 look more like Python 2.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/237


File: setuptools.info,  Node: 5 7,  Next: 5 6,  Prev: 5 8,  Up: History<2>

9.320 5.7
=========

15 Aug 2014

   * Issue #240(1): Based on real-world performance measures against
     5.4, zip manifests are now cached in all circumstances.  The
     ‘PKG_RESOURCES_CACHE_ZIP_MANIFESTS’ environment variable is no
     longer relevant.  The observed “memory increase” referenced in the
     5.4 release notes and detailed in Issue #154(2) was likely not an
     increase over the status quo, but rather only an increase over not
     storing the zip info at all.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/240

   (2) https://github.com/pypa/setuptools/issues/154


File: setuptools.info,  Node: 5 6,  Next: 5 5 1,  Prev: 5 7,  Up: History<2>

9.321 5.6
=========

14 Aug 2014

   * Issue #242(1): Use absolute imports in svn_utils to avoid issues if
     the installing package adds an xml module to the path.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/242


File: setuptools.info,  Node: 5 5 1,  Next: 5 5,  Prev: 5 6,  Up: History<2>

9.322 5.5.1
===========

10 Aug 2014

   * Issue #239(1): Fix typo in 5.5 such that fix did not take.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/239


File: setuptools.info,  Node: 5 5,  Next: 5 4 2,  Prev: 5 5 1,  Up: History<2>

9.323 5.5
=========

10 Aug 2014

   * Issue #239(1): Setuptools now includes the setup_requires directive
     on Distribution objects and validates the syntax just like
     install_requires and tests_require directives.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/239


File: setuptools.info,  Node: 5 4 2,  Next: 5 4 1,  Prev: 5 5,  Up: History<2>

9.324 5.4.2
===========

01 Aug 2014

   * Issue #236(1): Corrected regression in execfile implementation for
     Python 2.6.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/236


File: setuptools.info,  Node: 5 4 1,  Next: 5 4,  Prev: 5 4 2,  Up: History<2>

9.325 5.4.1
===========

06 Jul 2014

   * Python #7776(1): (ssl_support) Correct usage of host for validation
     when tunneling for HTTPS.

   ---------- Footnotes ----------

   (1) http://bugs.python.org/issue7776


File: setuptools.info,  Node: 5 4,  Next: 5 3,  Prev: 5 4 1,  Up: History<2>

9.326 5.4
=========

05 Jul 2014

   * Issue #154(1): ‘pkg_resources’ will now cache the zip manifests
     rather than re-processing the same file from disk multiple times,
     but only if the environment variable
     ‘PKG_RESOURCES_CACHE_ZIP_MANIFESTS’ is set.  Clients that package
     many modules in the same zip file will see some improvement in
     startup time by enabling this feature.  This feature is not enabled
     by default because it causes a substantial increase in memory
     usage.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/154


File: setuptools.info,  Node: 5 3,  Next: 5 2,  Prev: 5 4,  Up: History<2>

9.327 5.3
=========

28 Jun 2014

   * Issue #185(1): Make svn tagging work on the new style SVN metadata.
     Thanks cazabon!

   * Prune revision control directories (e.g .svn) from base path as
     well as sub-directories.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/185


File: setuptools.info,  Node: 5 2,  Next: 5 1,  Prev: 5 3,  Up: History<2>

9.328 5.2
=========

22 Jun 2014

   * Added a Developer Guide(1) to the official documentation.

   * Some code refactoring and cleanup was done with no intended
     behavioral changes.

   * During install_egg_info, the generated lines for namespace package
     .pth files are now processed even during a dry run.

   ---------- Footnotes ----------

   (1) https://setuptools.readthedocs.io/en/latest/developer-guide.html


File: setuptools.info,  Node: 5 1,  Next: 5 0 2,  Prev: 5 2,  Up: History<2>

9.329 5.1
=========

15 Jun 2014

   * Issue #202(1): Implemented more robust cache invalidation for the
     ZipImporter, building on the work in Issue #168(2).  Special thanks
     to Jurko Gospodnetic and PJE.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/202

   (2) https://github.com/pypa/setuptools/issues/168


File: setuptools.info,  Node: 5 0 2,  Next: 5 0 1,  Prev: 5 1,  Up: History<2>

9.330 5.0.2
===========

15 Jun 2014

   * Issue #220(1): Restored script templates.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/220


File: setuptools.info,  Node: 5 0 1,  Next: 5 0,  Prev: 5 0 2,  Up: History<2>

9.331 5.0.1
===========

14 Jun 2014

   * Renamed script templates to end with .tmpl now that they no longer
     need to be processed by 2to3.  Fixes spurious syntax errors during
     build/install.


File: setuptools.info,  Node: 5 0,  Next: 3 7 1 and 3 8 1 and 4 0 1,  Prev: 5 0 1,  Up: History<2>

9.332 5.0
=========

14 Jun 2014

   * Issue #218(1): Re-release of 3.8.1 to signal that it supersedes
     4.x.

   * Incidentally, script templates were updated not to include the
     triple-quote escaping.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/218


File: setuptools.info,  Node: 3 7 1 and 3 8 1 and 4 0 1,  Next: 4 0,  Prev: 5 0,  Up: History<2>

9.333 3.7.1 and 3.8.1 and 4.0.1
===============================

   * Issue #213(1): Use legacy StringIO behavior for compatibility under
     pbr.

   * Issue #218(2): Setuptools 3.8.1 superseded 4.0.1, and 4.x was
     removed from the available versions to install.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/213

   (2) https://github.com/pypa/setuptools/issues/218


File: setuptools.info,  Node: 4 0,  Next: 3 8,  Prev: 3 7 1 and 3 8 1 and 4 0 1,  Up: History<2>

9.334 4.0
=========

01 Jun 2014

   * Issue #210(1): ‘setup.py develop’ now copies scripts in binary mode
     rather than text mode, matching the behavior of the ‘install’
     command.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/210


File: setuptools.info,  Node: 3 8,  Next: 3 7,  Prev: 4 0,  Up: History<2>

9.335 3.8
=========

01 Jun 2014

   * Extend Issue #197(1) workaround to include all Python 3 versions
     prior to 3.2.2.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/197


File: setuptools.info,  Node: 3 7,  Next: 3 6,  Prev: 3 8,  Up: History<2>

9.336 3.7
=========

28 May 2014

   * Issue #193(1): Improved handling of Unicode filenames when building
     manifests.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/193


File: setuptools.info,  Node: 3 6,  Next: 3 5 2,  Prev: 3 7,  Up: History<2>

9.337 3.6
=========

07 May 2014

   * Issue #203(1): Honor proxy settings for Powershell downloader in
     the bootstrap routine.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/203


File: setuptools.info,  Node: 3 5 2,  Next: 3 5 1,  Prev: 3 6,  Up: History<2>

9.338 3.5.2
===========

07 May 2014

   * Issue #168(1): More robust handling of replaced zip files and stale
     caches.  Fixes ZipImportError complaining about a ‘bad local
     header’.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/168


File: setuptools.info,  Node: 3 5 1,  Next: 3 5,  Prev: 3 5 2,  Up: History<2>

9.339 3.5.1
===========

04 May 2014

   * Issue #199(1): Restored ‘install._install’ for compatibility with
     earlier NumPy versions.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/199


File: setuptools.info,  Node: 3 5,  Next: 3 4 4,  Prev: 3 5 1,  Up: History<2>

9.340 3.5
=========

03 May 2014

   * Issue #195(1): Follow symbolic links in find_packages (restoring
     behavior broken in 3.4).

   * Issue #197(2): On Python 3.1, PKG-INFO is now saved in a UTF-8
     encoding instead of ‘sys.getpreferredencoding’ to match the
     behavior on Python 2.6-3.4.

   * Issue #192(3): Preferred bootstrap location is now
     ‘https://bootstrap.pypa.io/ez_setup.py’ (mirrored from former
     location).

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/195

   (2) https://github.com/pypa/setuptools/issues/197

   (3) https://github.com/pypa/setuptools/issues/192


File: setuptools.info,  Node: 3 4 4,  Next: 3 4 3,  Prev: 3 5,  Up: History<2>

9.341 3.4.4
===========

11 Apr 2014

   * Issue #184(1): Correct failure where find_package over-matched
     packages when directory traversal isn’t short-circuited.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/184


File: setuptools.info,  Node: 3 4 3,  Next: 3 4 2,  Prev: 3 4 4,  Up: History<2>

9.342 3.4.3
===========

07 Apr 2014

   * Issue #183(1): Really fix test command with Python 3.1.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/183


File: setuptools.info,  Node: 3 4 2,  Next: 3 4 1,  Prev: 3 4 3,  Up: History<2>

9.343 3.4.2
===========

06 Apr 2014

   * Issue #183(1): Fix additional regression in test command on Python
     3.1.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/183


File: setuptools.info,  Node: 3 4 1,  Next: 3 4,  Prev: 3 4 2,  Up: History<2>

9.344 3.4.1
===========

30 Mar 2014

   * Issue #180(1): Fix regression in test command not caught by
     py.test-run tests.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/180


File: setuptools.info,  Node: 3 4,  Next: 3 3,  Prev: 3 4 1,  Up: History<2>

9.345 3.4
=========

30 Mar 2014

   * Issue #176(1): Add parameter to the test command to support a
     custom test runner: –test-runner or -r.

   * Issue #177(2): Now assume most common invocation to install command
     on platforms/environments without stack support (issuing a
     warning).  Setuptools now installs naturally on IronPython.
     Behavior on CPython should be unchanged.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/176

   (2) https://github.com/pypa/setuptools/issues/177


File: setuptools.info,  Node: 3 3,  Next: 3 2,  Prev: 3 4,  Up: History<2>

9.346 3.3
=========

16 Mar 2014

   * Add ‘include’ parameter to ‘setuptools.find_packages()’.


File: setuptools.info,  Node: 3 2,  Next: 3 1,  Prev: 3 3,  Up: History<2>

9.347 3.2
=========

14 Mar 2014

   * BB Pull Request #39(1): Add support for C++ targets from Cython
     ‘.pyx’ files.

   * Issue #162(2): Update dependency on certifi to 1.0.1.

   * Issue #164(3): Update dependency on wincertstore to 0.2.

   ---------- Footnotes ----------

   (1) https://bitbucket.org/pypa/setuptools/pull-request/39

   (2) https://github.com/pypa/setuptools/issues/162

   (3) https://github.com/pypa/setuptools/issues/164


File: setuptools.info,  Node: 3 1,  Next: 3 0 2,  Prev: 3 2,  Up: History<2>

9.348 3.1
=========

08 Mar 2014

   * Issue #161(1): Restore Features functionality to allow backward
     compatibility (for Features) until the uses of that functionality
     is sufficiently removed.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/161


File: setuptools.info,  Node: 3 0 2,  Next: 3 0 1,  Prev: 3 1,  Up: History<2>

9.349 3.0.2
===========

06 Mar 2014

   * Correct typo in previous bugfix.


File: setuptools.info,  Node: 3 0 1,  Next: 3 0,  Prev: 3 0 2,  Up: History<2>

9.350 3.0.1
===========

06 Mar 2014

   * Issue #157(1): Restore support for Python 2.6 in bootstrap script
     where ‘zipfile.ZipFile’ does not yet have support for context
     managers.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/157


File: setuptools.info,  Node: 3 0,  Next: 2 2,  Prev: 3 0 1,  Up: History<2>

9.351 3.0
=========

04 Mar 2014

   * Issue #125(1): Prevent Subversion support from creating a
     ~/.subversion directory just for checking the presence of a
     Subversion repository.

   * Issue #12(2): Namespace packages are now imported lazily.  That is,
     the mere declaration of a namespace package in an egg on ‘sys.path’
     no longer causes it to be imported when ‘pkg_resources’ is
     imported.  Note that this change means that all of a namespace
     package’s ‘__init__.py’ files must include a ‘declare_namespace()’
     call in order to ensure that they will be handled properly at
     runtime.  In 2.x it was possible to get away without including the
     declaration, but only at the cost of forcing namespace packages to
     be imported early, which 3.0 no longer does.

   * Issue #148(3): When building (bdist_egg), setuptools no longer adds
     ‘__init__.py’ files to namespace packages.  Any packages that rely
     on this behavior will need to create ‘__init__.py’ files and
     include the ‘declare_namespace()’.

   * Issue #7(4): Setuptools itself is now distributed as a zip archive
     in addition to tar archive.  ez_setup.py now uses zip archive.
     This approach avoids the potential security vulnerabilities
     presented by use of tar archives in ez_setup.py.  It also leverages
     the security features added to ZipFile.extract in Python 2.7.4.

   * Issue #65(5): Removed deprecated Features functionality.

   * BB Pull Request #28(6): Remove backport of ‘_bytecode_filenames’
     which is available in Python 2.6 and later, but also has better
     compatibility with Python 3 environments.

   * Issue #156(7): Fix spelling of __PYVENV_LAUNCHER__ variable.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/125

   (2) https://github.com/pypa/setuptools/issues/12

   (3) https://github.com/pypa/setuptools/issues/148

   (4) https://github.com/pypa/setuptools/issues/7

   (5) https://github.com/pypa/setuptools/issues/65

   (6) https://bitbucket.org/pypa/setuptools/pull-request/28

   (7) https://github.com/pypa/setuptools/issues/156


File: setuptools.info,  Node: 2 2,  Next: 2 1 2,  Prev: 3 0,  Up: History<2>

9.352 2.2
=========

07 Feb 2014

   * Issue #141(1): Restored fix for allowing setup_requires
     dependencies to override installed dependencies during setup.

   * Issue #128(2): Fixed issue where only the first dependency link was
     honored in a distribution where multiple dependency links were
     supplied.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/141

   (2) https://github.com/pypa/setuptools/issues/128


File: setuptools.info,  Node: 2 1 2,  Next: 2 1 1,  Prev: 2 2,  Up: History<2>

9.353 2.1.2
===========

05 Feb 2014

   * Issue #144(1): Read long_description using codecs module to avoid
     errors installing on systems where LANG=C.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/144


File: setuptools.info,  Node: 2 1 1,  Next: 2 1,  Prev: 2 1 2,  Up: History<2>

9.354 2.1.1
===========

05 Feb 2014

   * Issue #139(1): Fix regression in re_finder for CVS repos (and maybe
     Git repos as well).

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/139


File: setuptools.info,  Node: 2 1,  Next: 2 0 2,  Prev: 2 1 1,  Up: History<2>

9.355 2.1
=========

07 Jan 2014

   * Issue #129(1): Suppress inspection of ‘*.whl’ files when searching
     for files in a zip-imported file.

   * Issue #131(2): Fix RuntimeError when constructing an egg fetcher.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/129

   (2) https://github.com/pypa/setuptools/issues/131


File: setuptools.info,  Node: 2 0 2,  Next: 2 0 1,  Prev: 2 1,  Up: History<2>

9.356 2.0.2
===========

29 Dec 2013

   * Fix NameError during installation with Python implementations (e.g.
     Jython) not containing parser module.

   * Fix NameError in ‘sdist:re_finder’.


File: setuptools.info,  Node: 2 0 1,  Next: 2 0,  Prev: 2 0 2,  Up: History<2>

9.357 2.0.1
===========

15 Dec 2013

   * Issue #124(1): Fixed error in list detection in upload_docs.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/124


File: setuptools.info,  Node: 2 0,  Next: 1 4 2,  Prev: 2 0 1,  Up: History<2>

9.358 2.0
=========

07 Dec 2013

   * Issue #121(1): Exempt lib2to3 pickled grammars from
     DirectorySandbox.

   * Issue #41(2): Dropped support for Python 2.4 and Python 2.5.
     Clients requiring setuptools for those versions of Python should
     use setuptools 1.x.

   * Removed ‘setuptools.command.easy_install.HAS_USER_SITE’.  Clients
     expecting this boolean variable should use ‘site.ENABLE_USER_SITE’
     instead.

   * Removed ‘pkg_resources.ImpWrapper’.  Clients that expected this
     class should use ‘pkgutil.ImpImporter’ instead.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/121

   (2) https://github.com/pypa/setuptools/issues/41


File: setuptools.info,  Node: 1 4 2,  Next: 1 4 1,  Prev: 2 0,  Up: History<2>

9.359 1.4.2
===========

01 Dec 2013

   * Issue #116(1): Correct TypeError when reading a local package index
     on Python 3.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/116


File: setuptools.info,  Node: 1 4 1,  Next: 1 4,  Prev: 1 4 2,  Up: History<2>

9.360 1.4.1
===========

23 Nov 2013

   * Issue #114(1): Use ‘sys.getfilesystemencoding’ for decoding config
     in ‘bdist_wininst’ distributions.

   * Issue #105(2) and Issue #113(3): Establish a more robust technique
     for determining the terminal encoding:

          1. Try ``getpreferredencoding``
          2. If that returns US_ASCII or None, try the encoding from
             ``getdefaultlocale``. If that encoding was a "fallback" because Python
             could not figure it out from the environment or OS, encoding remains
             unresolved.
          3. If the encoding is resolved, then make sure Python actually implements
             the encoding.
          4. On the event of an error or unknown codec, revert to fallbacks
             (UTF-8 on Darwin, ASCII on everything else).
          5. On the encoding is 'mac-roman' on Darwin, use UTF-8 as 'mac-roman' was
             a bug on older Python releases.

          On a side note, it would seem that the encoding only matters for when SVN
          does not yet support ``--xml`` and when getting repository and svn version
          numbers. The ``--xml`` technique should yield UTF-8 according to some
          messages on the SVN mailing lists. So if the version numbers are always
          7-bit ASCII clean, it may be best to only support the file parsing methods
          for legacy SVN releases and support for SVN without the subprocess command
          would simple go away as support for the older SVNs does.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/114

   (2) https://github.com/pypa/setuptools/issues/105

   (3) https://github.com/pypa/setuptools/issues/113


File: setuptools.info,  Node: 1 4,  Next: 1 3 2,  Prev: 1 4 1,  Up: History<2>

9.361 1.4
=========

17 Nov 2013

   * Issue #27(1): ‘easy_install’ will now use credentials from .pypirc
     if present for connecting to the package index.

   * BB Pull Request #21(2): Omit unwanted newlines in
     ‘package_index._encode_auth’ when the username/password pair length
     indicates wrapping.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/27

   (2) https://bitbucket.org/pypa/setuptools/pull-request/21


File: setuptools.info,  Node: 1 3 2,  Next: 1 3 1,  Prev: 1 4,  Up: History<2>

9.362 1.3.2
===========

09 Nov 2013

   * Issue #99(1): Fix filename encoding issues in SVN support.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/99


File: setuptools.info,  Node: 1 3 1,  Next: 1 3,  Prev: 1 3 2,  Up: History<2>

9.363 1.3.1
===========

07 Nov 2013

   * Remove exuberant warning in SVN support when SVN is not used.


File: setuptools.info,  Node: 1 3,  Next: 1 2,  Prev: 1 3 1,  Up: History<2>

9.364 1.3
=========

03 Nov 2013

   * Address security vulnerability in SSL match_hostname check as
     reported in Python #17997(1).

   * Prefer backports.ssl_match_hostname(2) for backport implementation
     if present.

   * Correct NameError in ‘ssl_support’ module (‘socket.error’).

   ---------- Footnotes ----------

   (1) http://bugs.python.org/issue17997

   (2) https://pypi.org/project/backports.ssl_match_hostname/


File: setuptools.info,  Node: 1 2,  Next: 1 1 7,  Prev: 1 3,  Up: History<2>

9.365 1.2
=========

02 Nov 2013

   * Issue #26(1): Add support for SVN 1.7.  Special thanks to Philip
     Thiem for the contribution.

   * Issue #93(2): Wheels are now distributed with every release.  Note
     that as reported in Issue #108(3), as of Pip 1.4, scripts aren’t
     installed properly from wheels.  Therefore, if using Pip to install
     setuptools from a wheel, the ‘easy_install’ command will not be
     available.

   * Setuptools “natural” launcher support, introduced in 1.0, is now
     officially supported.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/26

   (2) https://github.com/pypa/setuptools/issues/93

   (3) https://github.com/pypa/setuptools/issues/108


File: setuptools.info,  Node: 1 1 7,  Next: 1 1 6,  Prev: 1 2,  Up: History<2>

9.366 1.1.7
===========

11 Apr 2013

   * Fixed behavior of NameError handling in ‘script template (dev).py’
     (script launcher for ‘develop’ installs).

   * ‘ez_setup.py’ now ensures partial downloads are cleaned up
     following a failed download.

   * Distribute #363(1) and Issue #55(2): Skip an sdist test that fails
     on locales other than UTF-8.

   ---------- Footnotes ----------

   (1) https://bitbucket.org/tarek/distribute/issue/363

   (2) https://github.com/pypa/setuptools/issues/55


File: setuptools.info,  Node: 1 1 6,  Next: 1 1 5,  Prev: 1 1 7,  Up: History<2>

9.367 1.1.6
===========

18 Sep 2013

   * Distribute #349(1): ‘sandbox.execfile’ now opens the target file in
     binary mode, thus honoring a BOM in the file when compiled.

   ---------- Footnotes ----------

   (1) https://bitbucket.org/tarek/distribute/issue/349


File: setuptools.info,  Node: 1 1 5,  Next: 1 1 4,  Prev: 1 1 6,  Up: History<2>

9.368 1.1.5
===========

12 Sep 2013

   * Issue #69(1): Second attempt at fix (logic was reversed).

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/69


File: setuptools.info,  Node: 1 1 4,  Next: 1 1 3,  Prev: 1 1 5,  Up: History<2>

9.369 1.1.4
===========

07 Sep 2013

   * Issue #77(1): Fix error in upload command (Python 2.4).

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/77


File: setuptools.info,  Node: 1 1 3,  Next: 1 1 2,  Prev: 1 1 4,  Up: History<2>

9.370 1.1.3
===========

06 Sep 2013

   * Fix NameError in previous patch.


File: setuptools.info,  Node: 1 1 2,  Next: 1 1 1,  Prev: 1 1 3,  Up: History<2>

9.371 1.1.2
===========

06 Sep 2013

   * Issue #69(1): Correct issue where 404 errors are returned for URLs
     with fragments in them (such as #egg=).

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/69


File: setuptools.info,  Node: 1 1 1,  Next: 1 1,  Prev: 1 1 2,  Up: History<2>

9.372 1.1.1
===========

03 Sep 2013

   * Issue #75(1): Add ‘--insecure’ option to ez_setup.py to accommodate
     environments where a trusted SSL connection cannot be validated.

   * Issue #76(2): Fix AttributeError in upload command with Python 2.4.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/75

   (2) https://github.com/pypa/setuptools/issues/76


File: setuptools.info,  Node: 1 1,  Next: 1 0,  Prev: 1 1 1,  Up: History<2>

9.373 1.1
=========

26 Aug 2013

   * Issue #71(1) (Distribute #333(2)): EasyInstall now puts less
     emphasis on the condition when a host is blocked via
     ‘--allow-hosts’.

   * Issue #72(3): Restored Python 2.4 compatibility in ‘ez_setup.py’.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/71

   (2) https://bitbucket.org/tarek/distribute/issue/333

   (3) https://github.com/pypa/setuptools/issues/72


File: setuptools.info,  Node: 1 0,  Next: 0 9 8,  Prev: 1 1,  Up: History<2>

9.374 1.0
=========

17 Aug 2013

   * Issue #60(1): On Windows, Setuptools supports deferring to another
     launcher, such as Vinay Sajip’s pylauncher(2) (included with Python
     3.3) to launch console and GUI scripts and not install its own
     launcher executables.  This experimental functionality is currently
     only enabled if the ‘SETUPTOOLS_LAUNCHER’ environment variable is
     set to “natural”.  In the future, this behavior may become default,
     but only after it has matured and seen substantial adoption.  The
     ‘SETUPTOOLS_LAUNCHER’ also accepts “executable” to force the
     default behavior of creating launcher executables.

   * Issue #63(3): Bootstrap script (ez_setup.py) now prefers
     Powershell, curl, or wget for retrieving the Setuptools tarball for
     improved security of the install.  The script will still fall back
     to a simple ‘urlopen’ on platforms that do not have these tools.

   * Issue #65(4): Deprecated the ‘Features’ functionality.

   * Issue #52(5): In ‘VerifyingHTTPSConn’, handle a tunnelled (proxied)
     connection.

* Menu:

* Backward-Incompatible Changes::

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/60

   (2) https://bitbucket.org/pypa/pylauncher

   (3) https://github.com/pypa/setuptools/issues/63

   (4) https://github.com/pypa/setuptools/issues/65

   (5) https://github.com/pypa/setuptools/issues/52


File: setuptools.info,  Node: Backward-Incompatible Changes,  Up: 1 0

9.374.1 Backward-Incompatible Changes
-------------------------------------

This release includes a couple of backward-incompatible changes, but
most if not all users will find 1.0 a drop-in replacement for 0.9.

   * Issue #50(1): Normalized API of environment marker support.
     Specifically, removed line number and filename from SyntaxErrors
     when returned from ‘pkg_resources.invalid_marker’.  Any clients
     depending on the specific string representation of exceptions
     returned by that function may need to be updated to account for
     this change.

   * Issue #50(2): SyntaxErrors generated by
     ‘pkg_resources.invalid_marker’ are normalized for
     cross-implementation consistency.

   * Removed ‘--ignore-conflicts-at-my-risk’ and ‘--delete-conflicting’
     options to easy_install.  These options have been deprecated since
     0.6a11.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/50

   (2) https://github.com/pypa/setuptools/issues/50


File: setuptools.info,  Node: 0 9 8,  Next: 0 9 7,  Prev: 1 0,  Up: History<2>

9.375 0.9.8
===========

25 Jul 2013

   * Issue #53(1): Fix NameErrors in ‘_vcs_split_rev_from_url’.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/53


File: setuptools.info,  Node: 0 9 7,  Next: 0 9 6,  Prev: 0 9 8,  Up: History<2>

9.376 0.9.7
===========

22 Jul 2013

   * Issue #49(1): Correct AttributeError on PyPy where a hashlib.HASH
     object does not have a ‘.name’ attribute.

   * Issue #34(2): Documentation now refers to bootstrap script in code
     repository referenced by bookmark.

   * Add underscore-separated keys to environment markers (markerlib).

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/49

   (2) https://github.com/pypa/setuptools/issues/34


File: setuptools.info,  Node: 0 9 6,  Next: 0 9 5,  Prev: 0 9 7,  Up: History<2>

9.377 0.9.6
===========

17 Jul 2013

   * Issue #44(1): Test failure on Python 2.4 when MD5 hash doesn’t have
     a ‘.name’ attribute.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/44


File: setuptools.info,  Node: 0 9 5,  Next: 0 9 4,  Prev: 0 9 6,  Up: History<2>

9.378 0.9.5
===========

15 Jul 2013

   * Python #17980(1): Fix security vulnerability in SSL certificate
     validation.

   ---------- Footnotes ----------

   (1) http://bugs.python.org/issue17980


File: setuptools.info,  Node: 0 9 4,  Next: 0 9 3,  Prev: 0 9 5,  Up: History<2>

9.379 0.9.4
===========

15 Jul 2013

   * Issue #43(1): Fix issue (introduced in 0.9.1) with version
     resolution when upgrading over other releases of Setuptools.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/43


File: setuptools.info,  Node: 0 9 3,  Next: 0 9 2,  Prev: 0 9 4,  Up: History<2>

9.380 0.9.3
===========

15 Jul 2013

   * Issue #42(1): Fix new ‘AttributeError’ introduced in last fix.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/42


File: setuptools.info,  Node: 0 9 2,  Next: 0 9 1,  Prev: 0 9 3,  Up: History<2>

9.381 0.9.2
===========

15 Jul 2013

   * Issue #42(1): Fix regression where blank checksums would trigger an
     ‘AttributeError’.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/42


File: setuptools.info,  Node: 0 9 1,  Next: 0 9,  Prev: 0 9 2,  Up: History<2>

9.382 0.9.1
===========

13 Jul 2013

   * Distribute #386(1): Allow other positional and keyword arguments to
     os.open.

   * Corrected dependency on certifi mis-referenced in 0.9.

   ---------- Footnotes ----------

   (1) https://bitbucket.org/tarek/distribute/issue/386


File: setuptools.info,  Node: 0 9,  Next: 0 8,  Prev: 0 9 1,  Up: History<2>

9.383 0.9
=========

13 Jul 2013

   * ‘package_index’ now validates hashes other than MD5 in download
     links.


File: setuptools.info,  Node: 0 8,  Next: 0 7 8,  Prev: 0 9,  Up: History<2>

9.384 0.8
=========

05 Jul 2013

   * Code base now runs on Python 2.4 - Python 3.3 without Python 2to3
     conversion.


File: setuptools.info,  Node: 0 7 8,  Next: 0 7 7,  Prev: 0 8,  Up: History<2>

9.385 0.7.8
===========

04 Jul 2013

   * Distribute #375(1): Yet another fix for yet another regression.

   ---------- Footnotes ----------

   (1) https://bitbucket.org/tarek/distribute/issue/375


File: setuptools.info,  Node: 0 7 7,  Next: 0 7 6,  Prev: 0 7 8,  Up: History<2>

9.386 0.7.7
===========

02 Jul 2013

   * Distribute #375(1): Repair AttributeError created in last release
     (redo).

   * Issue #30(2): Added test for get_cache_path.

   ---------- Footnotes ----------

   (1) https://bitbucket.org/tarek/distribute/issue/375

   (2) https://github.com/pypa/setuptools/issues/30


File: setuptools.info,  Node: 0 7 6,  Next: 0 7 5,  Prev: 0 7 7,  Up: History<2>

9.387 0.7.6
===========

02 Jul 2013

   * Distribute #375(1): Repair AttributeError created in last release.

   ---------- Footnotes ----------

   (1) https://bitbucket.org/tarek/distribute/issue/375


File: setuptools.info,  Node: 0 7 5,  Next: 0 7 4,  Prev: 0 7 6,  Up: History<2>

9.388 0.7.5
===========

29 Jun 2013

   * Issue #21(1): Restore Python 2.4 compatibility in
     ‘test_easy_install’.

   * Distribute #375(2): Merged additional warning from Distribute
     0.6.46.

   * Now honor the environment variable
     ‘SETUPTOOLS_DISABLE_VERSIONED_EASY_INSTALL_SCRIPT’ in addition to
     the now deprecated
     ‘DISTRIBUTE_DISABLE_VERSIONED_EASY_INSTALL_SCRIPT’.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/21

   (2) https://bitbucket.org/tarek/distribute/issue/375


File: setuptools.info,  Node: 0 7 4,  Next: 0 7 3,  Prev: 0 7 5,  Up: History<2>

9.389 0.7.4
===========

19 Jun 2013

   * Issue #20(1): Fix comparison of parsed SVN version on Python 3.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/20


File: setuptools.info,  Node: 0 7 3,  Next: 0 7 2,  Prev: 0 7 4,  Up: History<2>

9.390 0.7.3
===========

18 Jun 2013

   * Issue #1(1): Disable installation of Windows-specific files on
     non-Windows systems.

   * Use new sysconfig module with Python 2.7 or >=3.2.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/1


File: setuptools.info,  Node: 0 7 2,  Next: 0 7 1,  Prev: 0 7 3,  Up: History<2>

9.391 0.7.2
===========

09 Jun 2013

   * Issue #14(1): Use markerlib when the ‘parser’ module is not
     available.

   * Issue #10(2): ‘ez_setup.py’ now uses HTTPS to download setuptools
     from PyPI.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/14

   (2) https://github.com/pypa/setuptools/issues/10


File: setuptools.info,  Node: 0 7 1,  Next: 0 7,  Prev: 0 7 2,  Up: History<2>

9.392 0.7.1
===========

03 Jun 2013

   * Fix NameError (Issue #3(1)) again - broken in bad merge.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/3


File: setuptools.info,  Node: 0 7,  Next: 0 7b4,  Prev: 0 7 1,  Up: History<2>

9.393 0.7
=========

02 Jun 2013

   * Merged Setuptools and Distribute.  See docs/merge.txt for details.

Added several features that were slated for setuptools 0.6c12:

   * Index URL now defaults to HTTPS.

   * Added experimental environment marker support.  Now clients may
     designate a PEP-426(1) environment marker for “extra” dependencies.
     Setuptools uses this feature in ‘setup.py’ for optional SSL and
     certificate validation support on older platforms.  Based on
     Distutils-SIG discussions, the syntax is somewhat tentative.  There
     should probably be a PEP with a firmer spec before the feature
     should be considered suitable for use.

   * Added support for SSL certificate validation when installing
     packages from an HTTPS service.

   ---------- Footnotes ----------

   (1) https://www.python.org/dev/peps/pep-0426/


File: setuptools.info,  Node: 0 7b4,  Next: 0 6 49,  Prev: 0 7,  Up: History<2>

9.394 0.7b4
===========

   * Issue #3(1): Fixed NameError in SSL support.

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/3


File: setuptools.info,  Node: 0 6 49,  Next: 0 6 48,  Prev: 0 7b4,  Up: History<2>

9.395 0.6.49
============

04 Jul 2013

   * Move warning check in ‘get_cache_path’ to follow the directory
     creation to avoid errors when the cache path does not yet exist.
     Fixes the error reported in Distribute #375(1).

   ---------- Footnotes ----------

   (1) https://bitbucket.org/tarek/distribute/issue/375


File: setuptools.info,  Node: 0 6 48,  Next: 0 6 47,  Prev: 0 6 49,  Up: History<2>

9.396 0.6.48
============

02 Jul 2013

   * Correct AttributeError in ‘ResourceManager.get_cache_path’
     introduced in 0.6.46 (redo).


File: setuptools.info,  Node: 0 6 47,  Next: 0 6 46,  Prev: 0 6 48,  Up: History<2>

9.397 0.6.47
============

02 Jul 2013

   * Correct AttributeError in ‘ResourceManager.get_cache_path’
     introduced in 0.6.46.


File: setuptools.info,  Node: 0 6 46,  Next: 0 6 45,  Prev: 0 6 47,  Up: History<2>

9.398 0.6.46
============

29 Jun 2013

   * Distribute #375(1): Issue a warning if the PYTHON_EGG_CACHE or
     otherwise customized egg cache location specifies a directory
     that’s group- or world-writable.

   ---------- Footnotes ----------

   (1) https://bitbucket.org/tarek/distribute/issue/375


File: setuptools.info,  Node: 0 6 45,  Next: 0 6 44,  Prev: 0 6 46,  Up: History<2>

9.399 0.6.45
============

29 May 2013

   * Distribute #379(1): ‘distribute_setup.py’ now traps VersionConflict
     as well, restoring ability to upgrade from an older setuptools
     version.

   ---------- Footnotes ----------

   (1) https://bitbucket.org/tarek/distribute/issue/379


File: setuptools.info,  Node: 0 6 44,  Next: 0 6 43,  Prev: 0 6 45,  Up: History<2>

9.400 0.6.44
============

28 May 2013

   * ‘distribute_setup.py’ has been updated to allow Setuptools 0.7 to
     satisfy use_setuptools.


File: setuptools.info,  Node: 0 6 43,  Next: 0 6 42,  Prev: 0 6 44,  Up: History<2>

9.401 0.6.43
============

24 May 2013

   * Distribute #378(1): Restore support for Python 2.4 Syntax
     (regression in 0.6.42).

   ---------- Footnotes ----------

   (1) https://bitbucket.org/tarek/distribute/issue/378


File: setuptools.info,  Node: 0 6 42,  Next: 0 6 41,  Prev: 0 6 43,  Up: History<2>

9.402 0.6.42
============

24 May 2013

   * External links finder no longer yields duplicate links.

   * Distribute #337(1): Moved site.py to setuptools/site-patch.py
     (graft of very old patch from setuptools trunk which inspired PR
     #31(2)).

   ---------- Footnotes ----------

   (1) https://bitbucket.org/tarek/distribute/issue/337

   (2) https://github.com/pypa/setuptools/issues/31


File: setuptools.info,  Node: 0 6 41,  Next: 0 6 40,  Prev: 0 6 42,  Up: History<2>

9.403 0.6.41
============

24 May 2013

   * Distribute #27(1): Use public api for loading resources from zip
     files rather than the private method ‘_zip_directory_cache’.

   * Added a new function ‘easy_install.get_win_launcher’ which may be
     used by third-party libraries such as buildout to get a suitable
     script launcher.

   ---------- Footnotes ----------

   (1) https://bitbucket.org/tarek/distribute/issue/27


File: setuptools.info,  Node: 0 6 40,  Next: 0 6 39,  Prev: 0 6 41,  Up: History<2>

9.404 0.6.40
============

14 May 2013

   * Distribute #376(1): brought back cli.exe and gui.exe that were
     deleted in the previous release.

   ---------- Footnotes ----------

   (1) https://bitbucket.org/tarek/distribute/issue/376


File: setuptools.info,  Node: 0 6 39,  Next: 0 6 38,  Prev: 0 6 40,  Up: History<2>

9.405 0.6.39
============

12 May 2013

   * Add support for console launchers on ARM platforms.

   * Fix possible issue in GUI launchers where the subsystem was not
     supplied to the linker.

   * Launcher build script now refactored for robustness.

   * Distribute #375(1): Resources extracted from a zip egg to the file
     system now also check the contents of the file against the zip
     contents during each invocation of get_resource_filename.

   ---------- Footnotes ----------

   (1) https://bitbucket.org/tarek/distribute/issue/375


File: setuptools.info,  Node: 0 6 38,  Next: 0 6 37,  Prev: 0 6 39,  Up: History<2>

9.406 0.6.38
============

05 May 2013

   * Distribute #371(1): The launcher manifest file is now installed
     properly.

   ---------- Footnotes ----------

   (1) https://bitbucket.org/tarek/distribute/issue/371


File: setuptools.info,  Node: 0 6 37,  Next: 0 6 36,  Prev: 0 6 38,  Up: History<2>

9.407 0.6.37
============

04 May 2013

   * Distribute #143(1): Launcher scripts, including easy_install
     itself, are now accompanied by a manifest on 32-bit Windows
     environments to avoid the Installer Detection Technology and thus
     undesirable UAC elevation described in this Microsoft article(2).

   ---------- Footnotes ----------

   (1) https://bitbucket.org/tarek/distribute/issue/143

   (2) 
http://technet.microsoft.com/en-us/library/cc709628%28WS.10%29.aspx


File: setuptools.info,  Node: 0 6 36,  Next: 0 6 35,  Prev: 0 6 37,  Up: History<2>

9.408 0.6.36
============

05 Apr 2013

   * BB Pull Request #35(1): In Buildout #64(2), it was reported that
     under Python 3, installation of distutils scripts could attempt to
     copy the ‘__pycache__’ directory as a file, causing an error,
     apparently only under Windows.  Easy_install now skips all
     directories when processing metadata scripts.

   ---------- Footnotes ----------

   (1) https://bitbucket.org/pypa/setuptools/pull-request/35

   (2) https://github.com/buildout/buildout/issues/64


File: setuptools.info,  Node: 0 6 35,  Next: 0 6 34,  Prev: 0 6 36,  Up: History<2>

9.409 0.6.35
============

16 Feb 2013

Note this release is backward-incompatible with distribute 0.6.23-0.6.34
in how it parses version numbers.

   * Distribute #278(1): Restored compatibility with distribute 0.6.22
     and setuptools 0.6.  Updated the documentation to match more
     closely with the version parsing as intended in setuptools 0.6.

   ---------- Footnotes ----------

   (1) https://bitbucket.org/tarek/distribute/issue/278


File: setuptools.info,  Node: 0 6 34,  Next: 0 6 33,  Prev: 0 6 35,  Up: History<2>

9.410 0.6.34
============

30 Dec 2012

   * Distribute #341(1): 0.6.33 fails to build under Python 2.4.

   ---------- Footnotes ----------

   (1) https://bitbucket.org/tarek/distribute/issue/341


File: setuptools.info,  Node: 0 6 33,  Next: 0 6 32,  Prev: 0 6 34,  Up: History<2>

9.411 0.6.33
============

29 Dec 2012

   * Fix 2 errors with Jython 2.5.

   * Fix 1 failure with Jython 2.5 and 2.7.

   * Disable workaround for Jython scripts on Linux systems.

   * Distribute #336(1): ‘setup.py’ no longer masks failure exit code
     when tests fail.

   * Fix issue in pkg_resources where try/except around a
     platform-dependent import would trigger hook load failures on
     Mercurial.  See pull request 32 for details.

   * Distribute #341(2): Fix a ResourceWarning.

   ---------- Footnotes ----------

   (1) https://bitbucket.org/tarek/distribute/issue/336

   (2) https://bitbucket.org/tarek/distribute/issue/341


File: setuptools.info,  Node: 0 6 32,  Next: 0 6 31,  Prev: 0 6 33,  Up: History<2>

9.412 0.6.32
============

26 Nov 2012

   * Fix test suite with Python 2.6.

   * Fix some DeprecationWarnings and ResourceWarnings.

   * Distribute #335(1): Backed out ‘setup_requires’ superceding
     installed requirements until regression can be addressed.

   ---------- Footnotes ----------

   (1) https://bitbucket.org/tarek/distribute/issue/335


File: setuptools.info,  Node: 0 6 31,  Next: 0 6 30,  Prev: 0 6 32,  Up: History<2>

9.413 0.6.31
============

24 Nov 2012

   * Distribute #303(1): Make sure the manifest only ever contains UTF-8
     in Python 3.

   * Distribute #329(2): Properly close files created by tests for
     compatibility with Jython.

   * Work around Jython #1980(3) and Jython #1981(4).

   * Distribute #334(5): Provide workaround for packages that reference
     ‘sys.__stdout__’ such as numpy does.  This change should address
     virtualenv ‘#359(6)
     <‘https://github.com/pypa/virtualenv/issues/359’>‘_ as long as the
     system encoding is UTF-8 or the IO encoding is specified in the
     environment, i.e.:

          PYTHONIOENCODING=utf8 pip install numpy

   * Fix for encoding issue when installing from Windows executable on
     Python 3.

   * Distribute #323(7): Allow ‘setup_requires’ requirements to
     supercede installed requirements.  Added some new keyword arguments
     to existing pkg_resources methods.  Also had to updated how
     __path__ is handled for namespace packages to ensure that when a
     new egg distribution containing a namespace package is placed on
     sys.path, the entries in __path__ are found in the same order they
     would have been in had that egg been on the path when pkg_resources
     was first imported.

   ---------- Footnotes ----------

   (1) https://bitbucket.org/tarek/distribute/issue/303

   (2) https://bitbucket.org/tarek/distribute/issue/329

   (3) http://bugs.jython.org/issue1980

   (4) http://bugs.jython.org/issue1981

   (5) https://bitbucket.org/tarek/distribute/issue/334

   (6) https://github.com/pypa/setuptools/issues/359

   (7) https://bitbucket.org/tarek/distribute/issue/323


File: setuptools.info,  Node: 0 6 30,  Next: 0 6 29,  Prev: 0 6 31,  Up: History<2>

9.414 0.6.30
============

22 Oct 2012

   * Distribute #328(1): Clean up temporary directories in
     distribute_setup.py.

   * Fix fatal bug in distribute_setup.py.

   ---------- Footnotes ----------

   (1) https://bitbucket.org/tarek/distribute/issue/328


File: setuptools.info,  Node: 0 6 29,  Next: 0 6 28,  Prev: 0 6 30,  Up: History<2>

9.415 0.6.29
============

21 Oct 2012

   * BB Pull Request #14(1): Honor file permissions in zip files.

   * Distribute #327(2): Merged pull request #24(3) to fix a dependency
     problem with pip.

   * Merged pull request #23(4) to fix
     ‘https://github.com/pypa/virtualenv/issues/301’.

   * If Sphinx is installed, the ‘upload_docs’ command now runs
     ‘build_sphinx’ to produce uploadable documentation.

   * Distribute #326(5): ‘upload_docs’ provided mangled auth credentials
     under Python 3.

   * Distribute #320(6): Fix check for “createable” in
     distribute_setup.py.

   * Distribute #305(7): Remove a warning that was triggered during
     normal operations.

   * Distribute #311(8): Print metadata in UTF-8 independent of
     platform.

   * Distribute #303(9): Read manifest file with UTF-8 encoding under
     Python 3.

   * Distribute #301(10): Allow to run tests of namespace packages when
     using 2to3.

   * Distribute #304(11): Prevent import loop in site.py under Python
     3.3.

   * Distribute #283(12): Reenable scanning of ‘*.pyc’ / ‘*.pyo’ files
     on Python 3.3.

   * Distribute #299(13): The develop command didn’t work on Python 3,
     when using 2to3, as the egg link would go to the Python 2 source.
     Linking to the 2to3’d code in build/lib makes it work, although you
     will have to rebuild the module before testing it.

   * Distribute #306(14): Even if 2to3 is used, we build in-place under
     Python 2.

   * Distribute #307(15): Prints the full path when .svn/entries is
     broken.

   * Distribute #313(16): Support for sdist subcommands (Python 2.7)

   * Distribute #314(17): test_local_index() would fail an OS X.

   * Distribute #310(18): Non-ascii characters in a namespace
     __init__.py causes errors.

   * Distribute #218(19): Improved documentation on behavior of
     ‘package_data’ and ‘include_package_data’.  Files indicated by
     ‘package_data’ are now included in the manifest.

   * ‘distribute_setup.py’ now allows a ‘--download-base’ argument for
     retrieving distribute from a specified location.

   ---------- Footnotes ----------

   (1) https://bitbucket.org/pypa/setuptools/pull-request/14

   (2) https://bitbucket.org/tarek/distribute/issue/327

   (3) https://github.com/pypa/setuptools/issues/24

   (4) https://github.com/pypa/setuptools/issues/23

   (5) https://bitbucket.org/tarek/distribute/issue/326

   (6) https://bitbucket.org/tarek/distribute/issue/320

   (7) https://bitbucket.org/tarek/distribute/issue/305

   (8) https://bitbucket.org/tarek/distribute/issue/311

   (9) https://bitbucket.org/tarek/distribute/issue/303

   (10) https://bitbucket.org/tarek/distribute/issue/301

   (11) https://bitbucket.org/tarek/distribute/issue/304

   (12) https://bitbucket.org/tarek/distribute/issue/283

   (13) https://bitbucket.org/tarek/distribute/issue/299

   (14) https://bitbucket.org/tarek/distribute/issue/306

   (15) https://bitbucket.org/tarek/distribute/issue/307

   (16) https://bitbucket.org/tarek/distribute/issue/313

   (17) https://bitbucket.org/tarek/distribute/issue/314

   (18) https://bitbucket.org/tarek/distribute/issue/310

   (19) https://bitbucket.org/tarek/distribute/issue/218


File: setuptools.info,  Node: 0 6 28,  Next: 0 6 27,  Prev: 0 6 29,  Up: History<2>

9.416 0.6.28
============

22 Jul 2012

   * Distribute #294(1): setup.py can now be invoked from any directory.

   * Scripts are now installed honoring the umask.

   * Added support for .dist-info directories.

   * Distribute #283(2): Fix and disable scanning of ‘*.pyc’ / ‘*.pyo’
     files on Python 3.3.

   ---------- Footnotes ----------

   (1) https://bitbucket.org/tarek/distribute/issue/294

   (2) https://bitbucket.org/tarek/distribute/issue/283


File: setuptools.info,  Node: 0 6 27,  Next: 0 6 26,  Prev: 0 6 28,  Up: History<2>

9.417 0.6.27
============

18 May 2012

   * Support current snapshots of CPython 3.3.

   * Distribute now recognizes README.rst as a standard, default readme
     file.

   * Exclude ‘encodings’ modules when removing modules from sys.modules.
     Workaround for #285(1).

   * Distribute #231(2): Don’t fiddle with system python when used with
     buildout (bootstrap.py)

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/285

   (2) https://bitbucket.org/tarek/distribute/issue/231


File: setuptools.info,  Node: 0 6 26,  Next: 0 6 25,  Prev: 0 6 27,  Up: History<2>

9.418 0.6.26
============

08 Apr 2012

   * Distribute #183(1): Symlinked files are now extracted from source
     distributions.

   * Distribute #227(2): Easy_install fetch parameters are now passed
     during the installation of a source distribution; now fulfillment
     of setup_requires dependencies will honor the parameters passed to
     easy_install.

   ---------- Footnotes ----------

   (1) https://bitbucket.org/tarek/distribute/issue/183

   (2) https://bitbucket.org/tarek/distribute/issue/227


File: setuptools.info,  Node: 0 6 25,  Next: 0 6 24,  Prev: 0 6 26,  Up: History<2>

9.419 0.6.25
============

08 Feb 2012

   * Distribute #258(1): Workaround a cache issue

   * Distribute #260(2): distribute_setup.py now accepts the –user
     parameter for Python 2.6 and later.

   * Distribute #262(3): package_index.open_with_auth no longer throws
     LookupError on Python 3.

   * Distribute #269(4): AttributeError when an exception occurs reading
     Manifest.in on late releases of Python.

   * Distribute #272(5): Prevent TypeError when namespace package names
     are unicode and single-install-externally-managed is used.  Also
     fixes PIP issue 449.

   * Distribute #273(6): Legacy script launchers now install with
     Python2/3 support.

   ---------- Footnotes ----------

   (1) https://bitbucket.org/tarek/distribute/issue/258

   (2) https://bitbucket.org/tarek/distribute/issue/260

   (3) https://bitbucket.org/tarek/distribute/issue/262

   (4) https://bitbucket.org/tarek/distribute/issue/269

   (5) https://bitbucket.org/tarek/distribute/issue/272

   (6) https://bitbucket.org/tarek/distribute/issue/273


File: setuptools.info,  Node: 0 6 24,  Next: 0 6 23,  Prev: 0 6 25,  Up: History<2>

9.420 0.6.24
============

14 Oct 2011

   * Distribute #249(1): Added options to exclude 2to3 fixers

   ---------- Footnotes ----------

   (1) https://bitbucket.org/tarek/distribute/issue/249


File: setuptools.info,  Node: 0 6 23,  Next: 0 6 21,  Prev: 0 6 24,  Up: History<2>

9.421 0.6.23
============

22 Sep 2011

   * Distribute #244(1): Fixed a test

   * Distribute #243(2): Fixed a test

   * Distribute #239(3): Fixed a test

   * Distribute #240(4): Fixed a test

   * Distribute #241(5): Fixed a test

   * Distribute #237(6): Fixed a test

   * Distribute #238(7): easy_install now uses 64bit executable wrappers
     on 64bit Python

   * Distribute #208(8): Fixed parsed_versions, it now honors
     post-releases as noted in the documentation

   * Distribute #207(9): Windows cli and gui wrappers pass CTRL-C to
     child python process

   * Distribute #227(10): easy_install now passes its arguments to
     setup.py bdist_egg

   * Distribute #225(11): Fixed a NameError on Python 2.5, 2.4

   ---------- Footnotes ----------

   (1) https://bitbucket.org/tarek/distribute/issue/244

   (2) https://bitbucket.org/tarek/distribute/issue/243

   (3) https://bitbucket.org/tarek/distribute/issue/239

   (4) https://bitbucket.org/tarek/distribute/issue/240

   (5) https://bitbucket.org/tarek/distribute/issue/241

   (6) https://bitbucket.org/tarek/distribute/issue/237

   (7) https://bitbucket.org/tarek/distribute/issue/238

   (8) https://bitbucket.org/tarek/distribute/issue/208

   (9) https://bitbucket.org/tarek/distribute/issue/207

   (10) https://bitbucket.org/tarek/distribute/issue/227

   (11) https://bitbucket.org/tarek/distribute/issue/225


File: setuptools.info,  Node: 0 6 21,  Next: 0 6 20,  Prev: 0 6 23,  Up: History<2>

9.422 0.6.21
============

20 Aug 2011

   * Distribute #225(1): FIxed a regression on py2.4

   ---------- Footnotes ----------

   (1) https://bitbucket.org/tarek/distribute/issue/225


File: setuptools.info,  Node: 0 6 20,  Next: 0 6 19,  Prev: 0 6 21,  Up: History<2>

9.423 0.6.20
============

18 Aug 2011

   * Distribute #135(1): Include url in warning when processing URLs in
     package_index.

   * Distribute #212(2): Fix issue where easy_instal fails on Python 3
     on windows installer.

   * Distribute #213(3): Fix typo in documentation.

   ---------- Footnotes ----------

   (1) https://bitbucket.org/tarek/distribute/issue/135

   (2) https://bitbucket.org/tarek/distribute/issue/212

   (3) https://bitbucket.org/tarek/distribute/issue/213


File: setuptools.info,  Node: 0 6 19,  Next: 0 6 18,  Prev: 0 6 20,  Up: History<2>

9.424 0.6.19
============

02 Jun 2011

   * Distribute #206(1): AttributeError: ‘HTTPMessage’ object has no
     attribute ‘getheaders’

   ---------- Footnotes ----------

   (1) https://bitbucket.org/tarek/distribute/issue/206


File: setuptools.info,  Node: 0 6 18,  Next: 0 6 17,  Prev: 0 6 19,  Up: History<2>

9.425 0.6.18
============

01 Jun 2011

   * Distribute #210(1): Fixed a regression introduced by Distribute
     #204(2) fix.

   ---------- Footnotes ----------

   (1) https://bitbucket.org/tarek/distribute/issue/210

   (2) https://bitbucket.org/tarek/distribute/issue/204


File: setuptools.info,  Node: 0 6 17,  Next: 0 6 16,  Prev: 0 6 18,  Up: History<2>

9.426 0.6.17
============

30 May 2011

   * Support ‘DISTRIBUTE_DISABLE_VERSIONED_EASY_INSTALL_SCRIPT’
     environment variable to allow to disable installation of
     easy_install-${version} script.

   * Support Python >=3.1.4 and >=3.2.1.

   * Distribute #204(1): Don’t try to import the parent of a namespace
     package in declare_namespace

   * Distribute #196(2): Tolerate responses with multiple Content-Length
     headers

   * Distribute #205(3): Sandboxing doesn’t preserve working_set.  Leads
     to setup_requires problems.

   ---------- Footnotes ----------

   (1) https://bitbucket.org/tarek/distribute/issue/204

   (2) https://bitbucket.org/tarek/distribute/issue/196

   (3) https://bitbucket.org/tarek/distribute/issue/205


File: setuptools.info,  Node: 0 6 16,  Next: 0 6 15,  Prev: 0 6 17,  Up: History<2>

9.427 0.6.16
============

28 Apr 2011

   * Builds sdist gztar even on Windows (avoiding Distribute #193(1)).

   * Distribute #192(2): Fixed metadata omitted on Windows when
     package_dir specified with forward-slash.

   * Distribute #195(3): Cython build support.

   * Distribute #200(4): Issues with recognizing 64-bit packages on
     Windows.

   ---------- Footnotes ----------

   (1) https://bitbucket.org/tarek/distribute/issue/193

   (2) https://bitbucket.org/tarek/distribute/issue/192

   (3) https://bitbucket.org/tarek/distribute/issue/195

   (4) https://bitbucket.org/tarek/distribute/issue/200


File: setuptools.info,  Node: 0 6 15,  Next: 0 6 14,  Prev: 0 6 16,  Up: History<2>

9.428 0.6.15
============

12 Mar 2011

   * Fixed typo in bdist_egg

   * Several issues under Python 3 has been solved.

   * Distribute #146(1): Fixed missing DLL files after easy_install of
     windows exe package.

   ---------- Footnotes ----------

   (1) https://bitbucket.org/tarek/distribute/issue/146


File: setuptools.info,  Node: 0 6 14,  Next: 0 6 13,  Prev: 0 6 15,  Up: History<2>

9.429 0.6.14
============

15 Jul 2010

   * Distribute #170(1): Fixed unittest failure.  Thanks to Toshio.

   * Distribute #171(2): Fixed race condition in unittests cause
     deadlocks in test suite.

   * Distribute #143(3): Fixed a lookup issue with easy_install.  Thanks
     to David and Zooko.

   * Distribute #174(4): Fixed the edit mode when its used with
     setuptools itself

   ---------- Footnotes ----------

   (1) https://bitbucket.org/tarek/distribute/issue/170

   (2) https://bitbucket.org/tarek/distribute/issue/171

   (3) https://bitbucket.org/tarek/distribute/issue/143

   (4) https://bitbucket.org/tarek/distribute/issue/174


File: setuptools.info,  Node: 0 6 13,  Next: 0 6 12,  Prev: 0 6 14,  Up: History<2>

9.430 0.6.13
============

31 May 2010

   * Distribute #160(1): 2.7 gives ValueError(“Invalid IPv6 URL”)

   * Distribute #150(2): Fixed using ~/.local even in a
     –no-site-packages virtualenv

   * Distribute #163(3): scan index links before external links, and
     don’t use the md5 when comparing two distributions

   ---------- Footnotes ----------

   (1) https://bitbucket.org/tarek/distribute/issue/160

   (2) https://bitbucket.org/tarek/distribute/issue/150

   (3) https://bitbucket.org/tarek/distribute/issue/163


File: setuptools.info,  Node: 0 6 12,  Next: 0 6 11,  Prev: 0 6 13,  Up: History<2>

9.431 0.6.12
============

06 May 2010

   * Distribute #149(1): Fixed various failures on 2.3/2.4

   ---------- Footnotes ----------

   (1) https://bitbucket.org/tarek/distribute/issue/149


File: setuptools.info,  Node: 0 6 11,  Next: 0 6 10,  Prev: 0 6 12,  Up: History<2>

9.432 0.6.11
============

06 May 2010

   * Found another case of SandboxViolation - fixed

   * Distribute #15(1) and Distribute #48(2): Introduced a socket
     timeout of 15 seconds on url openings

   * Added indexsidebar.html into MANIFEST.in

   * Distribute #108(3): Fixed TypeError with Python3.1

   * Distribute #121(4): Fixed –help install command trying to actually
     install.

   * Distribute #112(5): Added an os.makedirs so that Tarek’s solution
     will work.

   * Distribute #133(6): Added –no-find-links to easy_install

   * Added easy_install –user

   * Distribute #100(7): Fixed develop –user not taking ‘.’ in
     PYTHONPATH into account

   * Distribute #134(8): removed spurious UserWarnings.  Patch by
     VanLindberg

   * Distribute #138(9): cant_write_to_target error when setup_requires
     is used.

   * Distribute #147(10): respect the sys.dont_write_bytecode flag

   ---------- Footnotes ----------

   (1) https://bitbucket.org/tarek/distribute/issue/15

   (2) https://bitbucket.org/tarek/distribute/issue/48

   (3) https://bitbucket.org/tarek/distribute/issue/108

   (4) https://bitbucket.org/tarek/distribute/issue/121

   (5) https://bitbucket.org/tarek/distribute/issue/112

   (6) https://bitbucket.org/tarek/distribute/issue/133

   (7) https://bitbucket.org/tarek/distribute/issue/100

   (8) https://bitbucket.org/tarek/distribute/issue/134

   (9) https://bitbucket.org/tarek/distribute/issue/138

   (10) https://bitbucket.org/tarek/distribute/issue/147


File: setuptools.info,  Node: 0 6 10,  Next: 0 6 9,  Prev: 0 6 11,  Up: History<2>

9.433 0.6.10
============

12 Dec 2009

   * Reverted change made for the DistributionNotFound exception because
     zc.buildout uses the exception message to get the name of the
     distribution.


File: setuptools.info,  Node: 0 6 9,  Next: 0 6 8,  Prev: 0 6 10,  Up: History<2>

9.434 0.6.9
===========

12 Dec 2009

   * Distribute #90(1): unknown setuptools version can be added in the
     working set

   * Distribute #87(2): setupt.py doesn’t try to convert
     distribute_setup.py anymore Initial Patch by arfrever.

   * Distribute #89(3): added a side bar with a download link to the
     doc.

   * Distribute #86(4): fixed missing sentence in pkg_resources doc.

   * Added a nicer error message when a DistributionNotFound is raised.

   * Distribute #80(5): test_develop now works with Python 3.1

   * Distribute #93(6): upload_docs now works if there is an empty
     sub-directory.

   * Distribute #70(7): exec bit on non-exec files

   * Distribute #99(8): now the standalone easy_install command doesn’t
     uses a “setup.cfg” if any exists in the working directory.  It will
     use it only if triggered by ‘install_requires’ from a setup.py call
     (install, develop, etc).

   * Distribute #101(9): Allowing ‘os.devnull’ in Sandbox

   * Distribute #92(10): Fixed the “no eggs” found error with MacPort
     (platform.mac_ver() fails)

   * Distribute #103(11): test_get_script_header_jython_workaround not
     run anymore under py3 with C or POSIX local.  Contributed by
     Arfrever.

   * Distribute #104(12): remvoved the assertion when the installation
     fails, with a nicer message for the end user.

   * Distribute #100(13): making sure there’s no SandboxViolation when
     the setup script patches setuptools.

   ---------- Footnotes ----------

   (1) https://bitbucket.org/tarek/distribute/issue/90

   (2) https://bitbucket.org/tarek/distribute/issue/87

   (3) https://bitbucket.org/tarek/distribute/issue/89

   (4) https://bitbucket.org/tarek/distribute/issue/86

   (5) https://bitbucket.org/tarek/distribute/issue/80

   (6) https://bitbucket.org/tarek/distribute/issue/93

   (7) https://bitbucket.org/tarek/distribute/issue/70

   (8) https://bitbucket.org/tarek/distribute/issue/99

   (9) https://bitbucket.org/tarek/distribute/issue/101

   (10) https://bitbucket.org/tarek/distribute/issue/92

   (11) https://bitbucket.org/tarek/distribute/issue/103

   (12) https://bitbucket.org/tarek/distribute/issue/104

   (13) https://bitbucket.org/tarek/distribute/issue/100


File: setuptools.info,  Node: 0 6 8,  Next: 0 6 7,  Prev: 0 6 9,  Up: History<2>

9.435 0.6.8
===========

01 Nov 2009

   * Added “check_packages” in dist.  (added in Setuptools 0.6c11)

   * Fixed the DONT_PATCH_SETUPTOOLS state.


File: setuptools.info,  Node: 0 6 7,  Next: 0 6 6,  Prev: 0 6 8,  Up: History<2>

9.436 0.6.7
===========

01 Nov 2009

   * Distribute #58(1): Added –user support to the develop command

   * Distribute #11(2): Generated scripts now wrap their call to the
     script entry point in the standard “if name == ‘main’”

   * Added the ‘DONT_PATCH_SETUPTOOLS’ environment variable, so
     virtualenv can drive an installation that doesn’t patch a global
     setuptools.

   * Reviewed unladen-swallow specific change from
     ‘http://code.google.com/p/unladen-swallow/source/detail?spec=svn875&r=719’
     and determined that it no longer applies.  Distribute should work
     fine with Unladen Swallow 2009Q3.

   * Distribute #21(3): Allow PackageIndex.open_url to gracefully handle
     all cases of a httplib.HTTPException instead of just InvalidURL and
     BadStatusLine.

   * Removed virtual-python.py from this distribution and updated
     documentation to point to the actively maintained virtualenv
     instead.

   * Distribute #64(4): use_setuptools no longer rebuilds the distribute
     egg every time it is run

   * use_setuptools now properly respects the requested version

   * use_setuptools will no longer try to import a distribute egg for
     the wrong Python version

   * Distribute #74(5): no_fake should be True by default.

   * Distribute #72(6): avoid a bootstrapping issue with easy_install -U

   ---------- Footnotes ----------

   (1) https://bitbucket.org/tarek/distribute/issue/58

   (2) https://bitbucket.org/tarek/distribute/issue/11

   (3) https://bitbucket.org/tarek/distribute/issue/21

   (4) https://bitbucket.org/tarek/distribute/issue/64

   (5) https://bitbucket.org/tarek/distribute/issue/74

   (6) https://bitbucket.org/tarek/distribute/issue/72


File: setuptools.info,  Node: 0 6 6,  Next: 0 6 5,  Prev: 0 6 7,  Up: History<2>

9.437 0.6.6
===========

15 Oct 2009

   * Unified the bootstrap file so it works on both py2.x and py3k
     without 2to3 (patch by Holger Krekel)


File: setuptools.info,  Node: 0 6 5,  Next: 0 6 4,  Prev: 0 6 6,  Up: History<2>

9.438 0.6.5
===========

15 Oct 2009

   * Distribute #65(1): cli.exe and gui.exe are now generated at build
     time, depending on the platform in use.

   * Distribute #67(2): Fixed doc typo (PEP 381(3)/PEP 382(4)).

   * Distribute no longer shadows setuptools if we require a 0.7-series
     setuptools.  And an error is raised when installing a 0.7
     setuptools with distribute.

   * When run from within buildout, no attempt is made to modify an
     existing setuptools egg, whether in a shared egg directory or a
     system setuptools.

   * Fixed a hole in sandboxing allowing builtin file to write outside
     of the sandbox.

   ---------- Footnotes ----------

   (1) https://bitbucket.org/tarek/distribute/issue/65

   (2) https://bitbucket.org/tarek/distribute/issue/67

   (3) https://www.python.org/dev/peps/pep-0381/

   (4) https://www.python.org/dev/peps/pep-0382/


File: setuptools.info,  Node: 0 6 4,  Next: 0 6 3,  Prev: 0 6 5,  Up: History<2>

9.439 0.6.4
===========

10 Oct 2009

   * Added the generation of ‘distribute_setup_3k.py’ during the
     release.  This closes Distribute #52(1).

   * Added an upload_docs command to easily upload project documentation
     to PyPI’s ‘https://pythonhosted.org’.  This close issue Distribute
     #56(2).

   * Fixed a bootstrap bug on the use_setuptools() API.

   ---------- Footnotes ----------

   (1) https://bitbucket.org/tarek/distribute/issue/52

   (2) https://bitbucket.org/tarek/distribute/issue/56


File: setuptools.info,  Node: 0 6 3,  Next: 0 6 2,  Prev: 0 6 4,  Up: History<2>

9.440 0.6.3
===========

27 Sep 2009

* Menu:

* setuptools::
* bootstrapping::


File: setuptools.info,  Node: setuptools,  Next: bootstrapping,  Up: 0 6 3

9.440.1 setuptools
------------------

   * Fixed a bunch of calls to file() that caused crashes on Python 3.


File: setuptools.info,  Node: bootstrapping,  Prev: setuptools,  Up: 0 6 3

9.440.2 bootstrapping
---------------------

   * Fixed a bug in sorting that caused bootstrap to fail on Python 3.


File: setuptools.info,  Node: 0 6 2,  Next: 0 6 1,  Prev: 0 6 3,  Up: History<2>

9.441 0.6.2
===========

26 Sep 2009

* Menu:

* setuptools: setuptools<2>.
* bootstrapping: bootstrapping<2>.


File: setuptools.info,  Node: setuptools<2>,  Next: bootstrapping<2>,  Up: 0 6 2

9.441.1 setuptools
------------------

   * Added Python 3 support; see docs/python3.txt.  This closes Old
     Setuptools #39(1).

   * Added option to run 2to3 automatically when installing on Python 3.
     This closes issue Distribute #31(2).

   * Fixed invalid usage of requirement.parse, that broke develop -d.
     This closes Old Setuptools #44(3).

   * Fixed script launcher for 64-bit Windows.  This closes Old
     Setuptools #2(4).

   * KeyError when compiling extensions.  This closes Old Setuptools
     #41(5).

   ---------- Footnotes ----------

   (1) http://bugs.python.org/setuptools/issue39

   (2) https://bitbucket.org/tarek/distribute/issue/31

   (3) http://bugs.python.org/setuptools/issue44

   (4) http://bugs.python.org/setuptools/issue2

   (5) http://bugs.python.org/setuptools/issue41


File: setuptools.info,  Node: bootstrapping<2>,  Prev: setuptools<2>,  Up: 0 6 2

9.441.2 bootstrapping
---------------------

   * Fixed bootstrap not working on Windows.  This closes issue
     Distribute #49(1).

   * Fixed 2.6 dependencies.  This closes issue Distribute #50(2).

   * Make sure setuptools is patched when running through easy_install
     This closes Old Setuptools #40(3).

   ---------- Footnotes ----------

   (1) https://bitbucket.org/tarek/distribute/issue/49

   (2) https://bitbucket.org/tarek/distribute/issue/50

   (3) http://bugs.python.org/setuptools/issue40


File: setuptools.info,  Node: 0 6 1,  Next: 0 6,  Prev: 0 6 2,  Up: History<2>

9.442 0.6.1
===========

08 Sep 2009

* Menu:

* setuptools: setuptools<3>.
* bootstrapping: bootstrapping<3>.


File: setuptools.info,  Node: setuptools<3>,  Next: bootstrapping<3>,  Up: 0 6 1

9.442.1 setuptools
------------------

   * package_index.urlopen now catches BadStatusLine and malformed url
     errors.  This closes Distribute #16(1) and Distribute #18(2).

   * zip_ok is now False by default.  This closes Old Setuptools #33(3).

   * Fixed invalid URL error catching.  Old Setuptools #20(4).

   * Fixed invalid bootstraping with easy_install installation
     (Distribute #40(5)).  Thanks to Florian Schulze for the help.

   * Removed buildout/bootstrap.py.  A new repository will create a
     specific bootstrap.py script.

   ---------- Footnotes ----------

   (1) https://bitbucket.org/tarek/distribute/issue/16

   (2) https://bitbucket.org/tarek/distribute/issue/18

   (3) http://bugs.python.org/setuptools/issue33

   (4) http://bugs.python.org/setuptools/issue20

   (5) https://bitbucket.org/tarek/distribute/issue/40


File: setuptools.info,  Node: bootstrapping<3>,  Prev: setuptools<3>,  Up: 0 6 1

9.442.2 bootstrapping
---------------------

   * The boostrap process leave setuptools alone if detected in the
     system and –root or –prefix is provided, but is not in the same
     location.  This closes Distribute #10(1).

   ---------- Footnotes ----------

   (1) https://bitbucket.org/tarek/distribute/issue/10


File: setuptools.info,  Node: 0 6,  Next: 0 6c9,  Prev: 0 6 1,  Up: History<2>

9.443 0.6
=========

09 Aug 2009

* Menu:

* setuptools: setuptools<4>.
* pkg_resources::
* easy_install::


File: setuptools.info,  Node: setuptools<4>,  Next: pkg_resources,  Up: 0 6

9.443.1 setuptools
------------------

   * Packages required at build time where not fully present at install
     time.  This closes Distribute #12(1).

   * Protected against failures in tarfile extraction.  This closes
     Distribute #10(2).

   * Made Jython api_tests.txt doctest compatible.  This closes
     Distribute #7(3).

   * sandbox.py replaced builtin type file with builtin function open.
     This closes Distribute #6(4).

   * Immediately close all file handles.  This closes Distribute #3(5).

   * Added compatibility with Subversion 1.6.  This references
     Distribute #1(6).

   ---------- Footnotes ----------

   (1) https://bitbucket.org/tarek/distribute/issue/12

   (2) https://bitbucket.org/tarek/distribute/issue/10

   (3) https://bitbucket.org/tarek/distribute/issue/7

   (4) https://bitbucket.org/tarek/distribute/issue/6

   (5) https://bitbucket.org/tarek/distribute/issue/3

   (6) https://bitbucket.org/tarek/distribute/issue/1


File: setuptools.info,  Node: pkg_resources,  Next: easy_install,  Prev: setuptools<4>,  Up: 0 6

9.443.2 pkg_resources
---------------------

   * Avoid a call to /usr/bin/sw_vers on OSX and use the official
     platform API instead.  Based on a patch from ronaldoussoren.  This
     closes issue #5(1).

   * Fixed a SandboxViolation for mkdir that could occur in certain
     cases.  This closes Distribute #13(2).

   * Allow to find_on_path on systems with tight permissions to fail
     gracefully.  This closes Distribute #9(3).

   * Corrected inconsistency between documentation and code of
     add_entry.  This closes Distribute #8(4).

   * Immediately close all file handles.  This closes Distribute #3(5).

   ---------- Footnotes ----------

   (1) https://github.com/pypa/setuptools/issues/5

   (2) https://bitbucket.org/tarek/distribute/issue/13

   (3) https://bitbucket.org/tarek/distribute/issue/9

   (4) https://bitbucket.org/tarek/distribute/issue/8

   (5) https://bitbucket.org/tarek/distribute/issue/3


File: setuptools.info,  Node: easy_install,  Prev: pkg_resources,  Up: 0 6

9.443.3 easy_install
--------------------

   * Immediately close all file handles.  This closes Distribute #3(1).

   ---------- Footnotes ----------

   (1) https://bitbucket.org/tarek/distribute/issue/3


File: setuptools.info,  Node: 0 6c9,  Next: 0 6c7,  Prev: 0 6,  Up: History<2>

9.444 0.6c9
===========

        * Fixed a missing files problem when using Windows source
          distributions on non-Windows platforms, due to distutils not
          handling manifest file line endings correctly.

        * Updated Pyrex support to work with Pyrex 0.9.6 and higher.

        * Minor changes for Jython compatibility, including skipping
          tests that can’t work on Jython.

        * Fixed not installing eggs in ‘install_requires’ if they were
          also used for ‘setup_requires’ or ‘tests_require’.

        * Fixed not fetching eggs in ‘install_requires’ when running
          tests.

        * Allow ‘ez_setup.use_setuptools()’ to upgrade existing
          setuptools installations when called from a standalone
          ‘setup.py’.

        * Added a warning if a namespace package is declared, but its
          parent package is not also declared as a namespace.

        * Support Subversion 1.5

        * Removed use of deprecated ‘md5’ module if ‘hashlib’ is
          available

        * Fixed ‘bdist_wininst upload’ trying to upload the ‘.exe’ twice

        * Fixed ‘bdist_egg’ putting a ‘native_libs.txt’ in the source
          package’s ‘.egg-info’, when it should only be in the built
          egg’s ‘EGG-INFO’.

        * Ensure that _full_name is set on all shared libs before
          extensions are checked for shared lib usage.  (Fixes a bug in
          the experimental shared library build support.)

        * Fix to allow unpacked eggs containing native libraries to fail
          more gracefully under Google App Engine (with an ‘ImportError’
          loading the C-based module, instead of getting a ‘NameError’).

        * Fixed ‘win32.exe’ support for .pth files, so unnecessary
          directory nesting is flattened out in the resulting egg.
          (There was a case-sensitivity problem that affected some
          distributions, notably ‘pywin32’.)

        * Prevent ‘--help-commands’ and other junk from showing under
          Python 2.5 when running ‘easy_install --help’.

        * Fixed GUI scripts sometimes not executing on Windows

        * Fixed not picking up dependency links from recursive
          dependencies.

        * Only make ‘.py’, ‘.dll’ and ‘.so’ files executable when
          unpacking eggs

        * Changes for Jython compatibility

        * Improved error message when a requirement is also a directory
          name, but the specified directory is not a source package.

        * Fixed ‘--allow-hosts’ option blocking ‘file:’ URLs

        * Fixed HTTP SVN detection failing when the page title included
          a project name (e.g.  on SourceForge-hosted SVN)

        * Fix Jython script installation to handle ‘#!’ lines better
          when ‘sys.executable’ is a script.

        * Removed use of deprecated ‘md5’ module if ‘hashlib’ is
          available

        * Keep site directories (e.g.  ‘site-packages’) from being
          included in ‘.pth’ files.


File: setuptools.info,  Node: 0 6c7,  Next: 0 6c6,  Prev: 0 6c9,  Up: History<2>

9.445 0.6c7
===========

        * Fixed ‘distutils.filelist.findall()’ crashing on broken
          symlinks, and ‘egg_info’ command failing on new, uncommitted
          SVN directories.

        * Fix import problems with nested namespace packages installed
          via ‘--root’ or ‘--single-version-externally-managed’, due to
          the parent package not having the child package as an
          attribute.

        * ‘ftp:’ download URLs now work correctly.

        * The default ‘--index-url’ is now
          ‘https://pypi.python.org/simple’, to use the Python Package
          Index’s new simpler (and faster!)  REST API.


File: setuptools.info,  Node: 0 6c6,  Next: 0 6c5,  Prev: 0 6c7,  Up: History<2>

9.446 0.6c6
===========

        * Added ‘--egg-path’ option to ‘develop’ command, allowing you
          to force ‘.egg-link’ files to use relative paths (allowing
          them to be shared across platforms on a networked drive).

        * Fix not building binary RPMs correctly.

        * Fix “eggsecutables” (such as setuptools’ own egg) only being
          runnable with bash-compatible shells.

        * Fix ‘#!’ parsing problems in Windows ‘.exe’ script wrappers,
          when there was whitespace inside a quoted argument or at the
          end of the ‘#!’ line (a regression introduced in 0.6c4).

        * Fix ‘test’ command possibly failing if an older version of the
          project being tested was installed on ‘sys.path’ ahead of the
          test source directory.

        * Fix ‘find_packages()’ treating ‘ez_setup’ and directories with
          ‘.’ in their names as packages.

        * EasyInstall no longer aborts the installation process if a URL
          it wants to retrieve can’t be downloaded, unless the URL is an
          actual package download.  Instead, it issues a warning and
          tries to keep going.

        * Fixed distutils-style scripts originally built on Windows
          having their line endings doubled when installed on any
          platform.

        * Added ‘--local-snapshots-ok’ flag, to allow building eggs from
          projects installed using ‘setup.py develop’.

        * Fixed not HTML-decoding URLs scraped from web pages


File: setuptools.info,  Node: 0 6c5,  Next: 0 6c4,  Prev: 0 6c6,  Up: History<2>

9.447 0.6c5
===========

        * Fix uploaded ‘bdist_rpm’ packages being described as
          ‘bdist_egg’ packages under Python versions less than 2.5.

        * Fix uploaded ‘bdist_wininst’ packages being described as
          suitable for “any” version by Python 2.5, even if a
          ‘--target-version’ was specified.

        * Fixed ‘.dll’ files on Cygwin not having executable permissions
          when an egg is installed unzipped.


File: setuptools.info,  Node: 0 6c4,  Next: 0 6c3,  Prev: 0 6c5,  Up: History<2>

9.448 0.6c4
===========

        * Overhauled Windows script wrapping to support ‘bdist_wininst’
          better.  Scripts installed with ‘bdist_wininst’ will always
          use ‘#!python.exe’ or ‘#!pythonw.exe’ as the executable name
          (even when built on non-Windows platforms!), and the wrappers
          will look for the executable in the script’s parent directory
          (which should find the right version of Python).

        * Fix ‘upload’ command not uploading files built by ‘bdist_rpm’
          or ‘bdist_wininst’ under Python 2.3 and 2.4.

        * Add support for “eggsecutable” headers: a ‘#!/bin/sh’ script
          that is prepended to an ‘.egg’ file to allow it to be run as a
          script on Unix-ish platforms.  (This is mainly so that
          setuptools itself can have a single-file installer on Unix,
          without doing multiple downloads, dealing with firewalls,
          etc.)

        * Fix problem with empty revision numbers in Subversion 1.4
          ‘entries’ files

        * Use cross-platform relative paths in ‘easy-install.pth’ when
          doing ‘develop’ and the source directory is a subdirectory of
          the installation target directory.

        * Fix a problem installing eggs with a system packaging tool if
          the project contained an implicit namespace package; for
          example if the ‘setup()’ listed a namespace package ‘foo.bar’
          without explicitly listing ‘foo’ as a namespace package.

        * Added support for HTTP “Basic” authentication using
          ‘http://user:pass@host’ URLs.  If a password-protected page
          contains links to the same host (and protocol), those links
          will inherit the credentials used to access the original page.

        * Removed all special support for Sourceforge mirrors, as
          Sourceforge’s mirror system now works well for non-browser
          downloads.

        * Fixed not recognizing ‘win32.exe’ installers that included a
          custom bitmap.

        * Fixed not allowing ‘os.open()’ of paths outside the sandbox,
          even if they are opened read-only (e.g.  reading
          ‘/dev/urandom’ for random numbers, as is done by
          ‘os.urandom()’ on some platforms).

        * Fixed a problem with ‘.pth’ testing on Windows when
          ‘sys.executable’ has a space in it (e.g., the user installed
          Python to a ‘Program Files’ directory).


File: setuptools.info,  Node: 0 6c3,  Next: 0 6c2,  Prev: 0 6c4,  Up: History<2>

9.449 0.6c3
===========

        * Fixed breakages caused by Subversion 1.4’s new “working copy”
          format

        * You can once again use “python -m easy_install” with Python
          2.4 and above.

        * Python 2.5 compatibility fixes added.


File: setuptools.info,  Node: 0 6c2,  Next: 0 6c1,  Prev: 0 6c3,  Up: History<2>

9.450 0.6c2
===========

        * The ‘ez_setup’ module displays the conflicting version of
          setuptools (and its installation location) when a script
          requests a version that’s not available.

        * Running ‘setup.py develop’ on a setuptools-using project will
          now install setuptools if needed, instead of only downloading
          the egg.

        * Windows script wrappers now support quoted arguments and
          arguments containing spaces.  (Patch contributed by Jim
          Fulton.)

        * The ‘ez_setup.py’ script now actually works when you put a
          setuptools ‘.egg’ alongside it for bootstrapping an offline
          machine.

        * A writable installation directory on ‘sys.path’ is no longer
          required to download and extract a source distribution using
          ‘--editable’.

        * Generated scripts now use ‘-x’ on the ‘#!’ line when
          ‘sys.executable’ contains non-ASCII characters, to prevent
          deprecation warnings about an unspecified encoding when the
          script is run.


File: setuptools.info,  Node: 0 6c1,  Next: 0 6b4,  Prev: 0 6c2,  Up: History<2>

9.451 0.6c1
===========

        * Fixed ‘AttributeError’ when trying to download a
          ‘setup_requires’ dependency when a distribution lacks a
          ‘dependency_links’ setting.

        * Made ‘zip-safe’ and ‘not-zip-safe’ flag files contain a single
          byte, so as to play better with packaging tools that complain
          about zero-length files.

        * Made ‘setup.py develop’ respect the ‘--no-deps’ option, which
          it previously was ignoring.

        * Support ‘extra_path’ option to ‘setup()’ when ‘install’ is run
          in backward-compatibility mode.

        * Source distributions now always include a ‘setup.cfg’ file
          that explicitly sets ‘egg_info’ options such that they produce
          an identical version number to the source distribution’s
          version number.  (Previously, the default version number could
          be different due to the use of ‘--tag-date’, or if the version
          was overridden on the command line that built the source
          distribution.)

        * EasyInstall now includes setuptools version information in the
          ‘User-Agent’ string sent to websites it visits.


File: setuptools.info,  Node: 0 6b4,  Next: 0 6b3,  Prev: 0 6c1,  Up: History<2>

9.452 0.6b4
===========

        * Fix ‘register’ not obeying name/version set by ‘egg_info’
          command, if ‘egg_info’ wasn’t explicitly run first on the same
          command line.

        * Added ‘--no-date’ and ‘--no-svn-revision’ options to
          ‘egg_info’ command, to allow suppressing tags configured in
          ‘setup.cfg’.

        * Fixed redundant warnings about missing ‘README’ file(s); it
          should now appear only if you are actually a source
          distribution.

        * Fix creating Python wrappers for non-Python scripts

        * Fix ‘ftp://’ directory listing URLs from causing a crash when
          used in the “Home page” or “Download URL” slots on PyPI.

        * Fix ‘sys.path_importer_cache’ not being updated when an
          existing zipfile or directory is deleted/overwritten.

        * Fix not recognizing HTML 404 pages from package indexes.

        * Allow ‘file://’ URLs to be used as a package index.  URLs that
          refer to directories will use an internally-generated
          directory listing if there is no ‘index.html’ file in the
          directory.

        * Allow external links in a package index to be specified using
          ‘rel="homepage"’ or ‘rel="download"’, without needing the old
          PyPI-specific visible markup.

        * Suppressed warning message about possibly-misspelled project
          name, if an egg or link for that project name has already been
          seen.


File: setuptools.info,  Node: 0 6b3,  Next: 0 6b2,  Prev: 0 6b4,  Up: History<2>

9.453 0.6b3
===========

        * Fix ‘bdist_egg’ not including files in subdirectories of
          ‘.egg-info’.

        * Allow ‘.py’ files found by the ‘include_package_data’ option
          to be automatically included.  Remove duplicate data file
          matches if both ‘include_package_data’ and ‘package_data’ are
          used to refer to the same files.

        * Fix local ‘--find-links’ eggs not being copied except with
          ‘--always-copy’.

        * Fix sometimes not detecting local packages installed outside
          of “site” directories.

        * Fix mysterious errors during initial ‘setuptools’ install,
          caused by ‘ez_setup’ trying to run ‘easy_install’ twice, due
          to a code fallthru after deleting the egg from which it’s
          running.


File: setuptools.info,  Node: 0 6b2,  Next: 0 6b1,  Prev: 0 6b3,  Up: History<2>

9.454 0.6b2
===========

        * Don’t install or update a ‘site.py’ patch when installing to a
          ‘PYTHONPATH’ directory with ‘--multi-version’, unless an
          ‘easy-install.pth’ file is already in use there.

        * Construct ‘.pth’ file paths in such a way that installing an
          egg whose name begins with ‘import’ doesn’t cause a syntax
          error.

        * Fixed a bogus warning message that wasn’t updated since the
          0.5 versions.


File: setuptools.info,  Node: 0 6b1,  Next: 0 6a11,  Prev: 0 6b2,  Up: History<2>

9.455 0.6b1
===========

        * Strip ‘module’ from the end of compiled extension modules when
          computing the name of a ‘.py’ loader/wrapper.  (Python’s
          import machinery ignores this suffix when searching for an
          extension module.)

        * Better ambiguity management: accept ‘#egg’ name/version even
          if processing what appears to be a correctly-named distutils
          file, and ignore ‘.egg’ files with no ‘-’, since valid Python
          ‘.egg’ files always have a version number (but Scheme eggs
          often don’t).

        * Support ‘file://’ links to directories in ‘--find-links’, so
          that easy_install can build packages from local source
          checkouts.

        * Added automatic retry for Sourceforge mirrors.  The new
          download process is to first just try dl.sourceforge.net, then
          randomly select mirror IPs and remove ones that fail, until
          something works.  The removed IPs stay removed for the
          remainder of the run.

        * Ignore bdist_dumb distributions when looking at download URLs.


File: setuptools.info,  Node: 0 6a11,  Next: 0 6a10,  Prev: 0 6b1,  Up: History<2>

9.456 0.6a11
============

        * Added ‘test_loader’ keyword to support custom test loaders

        * Added ‘setuptools.file_finders’ entry point group to allow
          implementing revision control plugins.

        * Added ‘--identity’ option to ‘upload’ command.

        * Added ‘dependency_links’ to allow specifying URLs for
          ‘--find-links’.

        * Enhanced test loader to scan packages as well as modules, and
          call ‘additional_tests()’ if present to get non-unittest
          tests.

        * Support namespace packages in conjunction with system
          packagers, by omitting the installation of any ‘__init__.py’
          files for namespace packages, and adding a special ‘.pth’ file
          to create a working package in ‘sys.modules’.

        * Made ‘--single-version-externally-managed’ automatic when
          ‘--root’ is used, so that most system packagers won’t require
          special support for setuptools.

        * Fixed ‘setup_requires’, ‘tests_require’, etc.  not using
          ‘setup.cfg’ or other configuration files for their option
          defaults when installing, and also made the install use
          ‘--multi-version’ mode so that the project directory doesn’t
          need to support .pth files.

        * ‘MANIFEST.in’ is now forcibly closed when any errors occur
          while reading it.  Previously, the file could be left open and
          the actual error would be masked by problems trying to remove
          the open file on Windows systems.

        * Process ‘dependency_links.txt’ if found in a distribution, by
          adding the URLs to the list for scanning.

        * Use relative paths in ‘.pth’ files when eggs are being
          installed to the same directory as the ‘.pth’ file.  This
          maximizes portability of the target directory when building
          applications that contain eggs.

        * Added ‘easy_install-N.N’ script(s) for convenience when using
          multiple Python versions.

        * Added automatic handling of installation conflicts.  Eggs are
          now shifted to the front of sys.path, in an order consistent
          with where they came from, making EasyInstall seamlessly
          co-operate with system package managers.

          The ‘--delete-conflicting’ and ‘--ignore-conflicts-at-my-risk’
          options are now no longer necessary, and will generate
          warnings at the end of a run if you use them.

        * Don’t recursively traverse subdirectories given to
          ‘--find-links’.


File: setuptools.info,  Node: 0 6a10,  Next: 0 6a9,  Prev: 0 6a11,  Up: History<2>

9.457 0.6a10
============

        * Fixed the ‘develop’ command ignoring ‘--find-links’.

        * Added exhaustive testing of the install directory, including a
          spawn test for ‘.pth’ file support, and directory
          writability/existence checks.  This should virtually eliminate
          the need to set or configure ‘--site-dirs’.

        * Added ‘--prefix’ option for more do-what-I-mean-ishness in the
          absence of RTFM-ing.  :)

        * Enhanced ‘PYTHONPATH’ support so that you don’t have to put
          any eggs on it manually to make it work.  ‘--multi-version’ is
          no longer a silent default; you must explicitly use it if
          installing to a non-PYTHONPATH, non-“site” directory.

        * Expand ‘$variables’ used in the ‘--site-dirs’,
          ‘--build-directory’, ‘--install-dir’, and ‘--script-dir’
          options, whether on the command line or in configuration
          files.

        * Improved SourceForge mirror processing to work faster and be
          less affected by transient HTML changes made by SourceForge.

        * PyPI searches now use the exact spelling of requirements
          specified on the command line or in a project’s
          ‘install_requires’.  Previously, a normalized form of the name
          was used, which could lead to unnecessary full-index searches
          when a project’s name had an underscore (‘_’) in it.

        * EasyInstall can now download bare ‘.py’ files and wrap them in
          an egg, as long as you include an ‘#egg=name-version’ suffix
          on the URL, or if the ‘.py’ file is listed as the “Download
          URL” on the project’s PyPI page.  This allows third parties to
          “package” trivial Python modules just by linking to them (e.g.
          from within their own PyPI page or download links page).

        * The ‘--always-copy’ option now skips “system” and
          “development” eggs since they can’t be reliably copied.  Note
          that this may cause EasyInstall to choose an older version of
          a package than what you expected, or it may cause downloading
          and installation of a fresh version of what’s already
          installed.

        * The ‘--find-links’ option previously scanned all supplied URLs
          and directories as early as possible, but now only directories
          and direct archive links are scanned immediately.  URLs are
          not retrieved unless a package search was already going to go
          online due to a package not being available locally, or due to
          the use of the ‘--update’ or ‘-U’ option.

        * Fixed the annoying ‘--help-commands’ wart.


File: setuptools.info,  Node: 0 6a9,  Next: 0 6a8,  Prev: 0 6a10,  Up: History<2>

9.458 0.6a9
===========

        * The ‘sdist’ command no longer uses the traditional ‘MANIFEST’
          file to create source distributions.  ‘MANIFEST.in’ is still
          read and processed, as are the standard defaults and pruning.
          But the manifest is built inside the project’s ‘.egg-info’
          directory as ‘SOURCES.txt’, and it is rebuilt every time the
          ‘egg_info’ command is run.

        * Added the ‘include_package_data’ keyword to ‘setup()’,
          allowing you to automatically include any package data listed
          in revision control or ‘MANIFEST.in’

        * Added the ‘exclude_package_data’ keyword to ‘setup()’,
          allowing you to trim back files included via the
          ‘package_data’ and ‘include_package_data’ options.

        * Fixed ‘--tag-svn-revision’ not working when run from a source
          distribution.

        * Added warning for namespace packages with missing
          ‘declare_namespace()’

        * Added ‘tests_require’ keyword to ‘setup()’, so that e.g.
          packages requiring ‘nose’ to run unit tests can make this
          dependency optional unless the ‘test’ command is run.

        * Made all commands that use ‘easy_install’ respect its
          configuration options, as this was causing some problems with
          ‘setup.py install’.

        * Added an ‘unpack_directory()’ driver to
          ‘setuptools.archive_util’, so that you can process a directory
          tree through a processing filter as if it were a zipfile or
          tarfile.

        * Added an internal ‘install_egg_info’ command to use as part of
          old-style ‘install’ operations, that installs an ‘.egg-info’
          directory with the package.

        * Added a ‘--single-version-externally-managed’ option to the
          ‘install’ command so that you can more easily wrap a “flat”
          egg in a system package.

        * Enhanced ‘bdist_rpm’ so that it installs single-version eggs
          that don’t rely on a ‘.pth’ file.  The ‘--no-egg’ option has
          been removed, since all RPMs are now built in a more
          backwards-compatible format.

        * Support full roundtrip translation of eggs to and from
          ‘bdist_wininst’ format.  Running ‘bdist_wininst’ on a
          setuptools-based package wraps the egg in an .exe that will
          safely install it as an egg (i.e., with metadata and
          entry-point wrapper scripts), and ‘easy_install’ can turn the
          .exe back into an ‘.egg’ file or directory and install it as
          such.

        * Fixed ‘.pth’ file processing picking up nested eggs (i.e.
          ones inside “baskets”) when they weren’t explicitly listed in
          the ‘.pth’ file.

        * If more than one URL appears to describe the exact same
          distribution, prefer the shortest one.  This helps to avoid
          “table of contents” CGI URLs like the ones on effbot.org.

        * Quote arguments to python.exe (including python’s path) to
          avoid problems when Python (or a script) is installed in a
          directory whose name contains spaces on Windows.

        * Support full roundtrip translation of eggs to and from
          ‘bdist_wininst’ format.  Running ‘bdist_wininst’ on a
          setuptools-based package wraps the egg in an .exe that will
          safely install it as an egg (i.e., with metadata and
          entry-point wrapper scripts), and ‘easy_install’ can turn the
          .exe back into an ‘.egg’ file or directory and install it as
          such.


File: setuptools.info,  Node: 0 6a8,  Next: 0 6a7,  Prev: 0 6a9,  Up: History<2>

9.459 0.6a8
===========

        * Fixed some problems building extensions when Pyrex was
          installed, especially with Python 2.4 and/or packages using
          SWIG.

        * Made ‘develop’ command accept all the same options as
          ‘easy_install’, and use the ‘easy_install’ command’s
          configuration settings as defaults.

        * Made ‘egg_info --tag-svn-revision’ fall back to extracting the
          revision number from ‘PKG-INFO’ in case it is being run on a
          source distribution of a snapshot taken from a
          Subversion-based project.

        * Automatically detect ‘.dll’, ‘.so’ and ‘.dylib’ files that are
          being installed as data, adding them to ‘native_libs.txt’
          automatically.

        * Fixed some problems with fresh checkouts of projects that
          don’t include ‘.egg-info/PKG-INFO’ under revision control and
          put the project’s source code directly in the project
          directory.  If such a package had any requirements that get
          processed before the ‘egg_info’ command can be run, the setup
          scripts would fail with a “Missing ‘Version:’ header and/or
          PKG-INFO file” error, because the egg runtime interpreted the
          unbuilt metadata in a directory on ‘sys.path’ (i.e.  the
          current directory) as being a corrupted egg.  Setuptools now
          monkeypatches the distribution metadata cache to pretend that
          the egg has valid version information, until it has a chance
          to make it actually be so (via the ‘egg_info’ command).

        * Update for changed SourceForge mirror format

        * Fixed not installing dependencies for some packages fetched
          via Subversion

        * Fixed dependency installation with ‘--always-copy’ not using
          the same dependency resolution procedure as other operations.

        * Fixed not fully removing temporary directories on Windows, if
          a Subversion checkout left read-only files behind

        * Fixed some problems building extensions when Pyrex was
          installed, especially with Python 2.4 and/or packages using
          SWIG.


File: setuptools.info,  Node: 0 6a7,  Next: 0 6a6,  Prev: 0 6a8,  Up: History<2>

9.460 0.6a7
===========

        * Fixed not being able to install Windows script wrappers using
          Python 2.3


File: setuptools.info,  Node: 0 6a6,  Next: 0 6a5,  Prev: 0 6a7,  Up: History<2>

9.461 0.6a6
===========

        * Added support for “traditional” PYTHONPATH-based non-root
          installation, and also the convenient ‘virtual-python.py’
          script, based on a contribution by Ian Bicking.  The
          setuptools egg now contains a hacked ‘site’ module that makes
          the PYTHONPATH-based approach work with .pth files, so that
          you can get the full EasyInstall feature set on such
          installations.

        * Added ‘--no-deps’ and ‘--allow-hosts’ options.

        * Improved Windows ‘.exe’ script wrappers so that the script can
          have the same name as a module without confusing Python.

        * Changed dependency processing so that it’s breadth-first,
          allowing a depender’s preferences to override those of a
          dependee, to prevent conflicts when a lower version is
          acceptable to the dependee, but not the depender.  Also,
          ensure that currently installed/selected packages aren’t given
          precedence over ones desired by a package being installed,
          which could cause conflict errors.


File: setuptools.info,  Node: 0 6a5,  Next: 0 6a3,  Prev: 0 6a6,  Up: History<2>

9.462 0.6a5
===========

        * Fixed missing gui/cli .exe files in distribution.  Fixed bugs
          in tests.


File: setuptools.info,  Node: 0 6a3,  Next: 0 6a2,  Prev: 0 6a5,  Up: History<2>

9.463 0.6a3
===========

        * Added ‘gui_scripts’ entry point group to allow installing GUI
          scripts on Windows and other platforms.  (The special handling
          is only for Windows; other platforms are treated the same as
          for ‘console_scripts’.)

        * Improved error message when trying to use old ways of running
          ‘easy_install’.  Removed the ability to run via ‘python -m’ or
          by running ‘easy_install.py’; ‘easy_install’ is the command to
          run on all supported platforms.

        * Improved wrapper script generation and runtime initialization
          so that a VersionConflict doesn’t occur if you later install a
          competing version of a needed package as the default version
          of that package.

        * Fixed a problem parsing version numbers in ‘#egg=’ links.


File: setuptools.info,  Node: 0 6a2,  Next: 0 6a1,  Prev: 0 6a3,  Up: History<2>

9.464 0.6a2
===========

        * Added ‘console_scripts’ entry point group to allow installing
          scripts without the need to create separate script files.  On
          Windows, console scripts get an ‘.exe’ wrapper so you can just
          type their name.  On other platforms, the scripts are written
          without a file extension.

        * EasyInstall can now install “console_scripts” defined by
          packages that use ‘setuptools’ and define appropriate entry
          points.  On Windows, console scripts get an ‘.exe’ wrapper so
          you can just type their name.  On other platforms, the scripts
          are installed without a file extension.

        * Using ‘python -m easy_install’ or running ‘easy_install.py’ is
          now DEPRECATED, since an ‘easy_install’ wrapper is now
          available on all platforms.


File: setuptools.info,  Node: 0 6a1,  Next: 0 5a12,  Prev: 0 6a2,  Up: History<2>

9.465 0.6a1
===========

        * Added support for building “old-style” RPMs that don’t install
          an egg for the target package, using a ‘--no-egg’ option.

        * The ‘build_ext’ command now works better when using the
          ‘--inplace’ option and multiple Python versions.  It now makes
          sure that all extensions match the current Python version,
          even if newer copies were built for a different Python
          version.

        * The ‘upload’ command no longer attaches an extra ‘.zip’ when
          uploading eggs, as PyPI now supports egg uploads without
          trickery.

        * The ‘ez_setup’ script/module now displays a warning before
          downloading the setuptools egg, and attempts to check the
          downloaded egg against an internal MD5 checksum table.

        * Fixed the ‘--tag-svn-revision’ option of ‘egg_info’ not
          finding the latest revision number; it was using the revision
          number of the directory containing ‘setup.py’, not the highest
          revision number in the project.

        * Added ‘eager_resources’ setup argument

        * The ‘sdist’ command now recognizes Subversion “deleted file”
          entries and does not include them in source distributions.

        * ‘setuptools’ now embeds itself more thoroughly into the
          distutils, so that other distutils extensions (e.g.  py2exe,
          py2app) will subclass setuptools’ versions of things, rather
          than the native distutils ones.

        * Added ‘entry_points’ and ‘setup_requires’ arguments to
          ‘setup()’; ‘setup_requires’ allows you to automatically find
          and download packages that are needed in order to `build' your
          project (as opposed to running it).

        * ‘setuptools’ now finds its commands, ‘setup()’ argument
          validators, and metadata writers using entry points, so that
          they can be extended by third-party packages.  See Creating
          distutils Extensions(1) for more details.

        * The vestigial ‘depends’ command has been removed.  It was
          never finished or documented, and never would have worked
          without EasyInstall - which it pre-dated and was never
          compatible with.

        * EasyInstall now does MD5 validation of downloads from PyPI, or
          from any link that has an “#md5=…” trailer with a 32-digit
          lowercase hex md5 digest.

        * EasyInstall now handles symlinks in target directories by
          removing the link, rather than attempting to overwrite the
          link’s destination.  This makes it easier to set up an
          alternate Python “home” directory (as described in the
          Non-Root Installation section of the docs).

        * Added support for handling MacOS platform information in
          ‘.egg’ filenames, based on a contribution by Kevin Dangoor.
          You may wish to delete and reinstall any eggs whose filename
          includes “darwin” and “Power_Macintosh”, because the format
          for this platform information has changed so that minor OS X
          upgrades (such as 10.4.1 to 10.4.2) do not cause eggs built
          with a previous OS version to become obsolete.

        * easy_install’s dependency processing algorithms have changed.
          When using ‘--always-copy’, it now ensures that dependencies
          are copied too.  When not using ‘--always-copy’, it tries to
          use a single resolution loop, rather than recursing.

        * Fixed installing extra ‘.pyc’ or ‘.pyo’ files for scripts with
          ‘.py’ extensions.

        * Added ‘--site-dirs’ option to allow adding custom “site”
          directories.  Made ‘easy-install.pth’ work in
          platform-specific alternate site directories (e.g.
          ‘~/Library/Python/2.x/site-packages’ on Mac OS X).

        * If you manually delete the current version of a package, the
          next run of EasyInstall against the target directory will now
          remove the stray entry from the ‘easy-install.pth’ file.

        * EasyInstall now recognizes URLs with a ‘#egg=project_name’
          fragment ID as pointing to the named project’s source
          checkout.  Such URLs have a lower match precedence than any
          other kind of distribution, so they’ll only be used if they
          have a higher version number than any other available
          distribution, or if you use the ‘--editable’ option.  The
          ‘#egg’ fragment can contain a version if it’s formatted as
          ‘#egg=proj-ver’, where ‘proj’ is the project name, and ‘ver’
          is the version number.  You `must' use the format for these
          values that the ‘bdist_egg’ command uses; i.e., all
          non-alphanumeric runs must be condensed to single underscore
          characters.

        * Added the ‘--editable’ option; see Editing and Viewing Source
          Packages in the docs.  Also, slightly changed the behavior of
          the ‘--build-directory’ option.

        * Fixed the setup script sandbox facility not recognizing
          certain paths as valid on case-insensitive platforms.

   ---------- Footnotes ----------

   (1) 
https://setuptools.readthedocs.io/en/latest/setuptools.html#creating-distutils-extensions


File: setuptools.info,  Node: 0 5a12,  Next: 0 5a11,  Prev: 0 6a1,  Up: History<2>

9.466 0.5a12
============

        * The zip-safety scanner now checks for modules that might be
          used with ‘python -m’, and marks them as unsafe for zipping,
          since Python 2.4 can’t handle ‘-m’ on zipped modules.

        * Fix ‘python -m easy_install’ not working due to setuptools
          being installed as a zipfile.  Update safety scanner to check
          for modules that might be used as ‘python -m’ scripts.

        * Misc.  fixes for win32.exe support, including changes to
          support Python 2.4’s changed ‘bdist_wininst’ format.


File: setuptools.info,  Node: 0 5a11,  Next: 0 5a10,  Prev: 0 5a12,  Up: History<2>

9.467 0.5a11
============

        * Fix breakage of the “develop” command that was caused by the
          addition of ‘--always-unzip’ to the ‘easy_install’ command.


File: setuptools.info,  Node: 0 5a10,  Next: 0 5a9,  Prev: 0 5a11,  Up: History<2>

9.468 0.5a10
============

        * Put the ‘easy_install’ module back in as a module, as it’s
          needed for ‘python -m’ to run it!

        * Allow ‘--find-links/-f’ to accept local directories or
          filenames as well as URLs.


File: setuptools.info,  Node: 0 5a9,  Next: 0 5a8,  Prev: 0 5a10,  Up: History<2>

9.469 0.5a9
===========

        * Include ‘svn:externals’ directories in source distributions as
          well as normal subversion-controlled files and directories.

        * Added ‘exclude=patternlist’ option to
          ‘setuptools.find_packages()’

        * Changed –tag-svn-revision to include an “r” in front of the
          revision number for better readability.

        * Added ability to build eggs without including source files
          (except for any scripts, of course), using the
          ‘--exclude-source-files’ option to ‘bdist_egg’.

        * ‘setup.py install’ now automatically detects when an
          “unmanaged” package or module is going to be on ‘sys.path’
          ahead of a package being installed, thereby preventing the
          newer version from being imported.  If this occurs, a warning
          message is output to ‘sys.stderr’, but installation proceeds
          anyway.  The warning message informs the user what files or
          directories need deleting, and advises them they can also use
          EasyInstall (with the ‘--delete-conflicting’ option) to do it
          automatically.

        * The ‘egg_info’ command now adds a ‘top_level.txt’ file to the
          metadata directory that lists all top-level modules and
          packages in the distribution.  This is used by the
          ‘easy_install’ command to find possibly-conflicting
          “unmanaged” packages when installing the distribution.

        * Added ‘zip_safe’ and ‘namespace_packages’ arguments to
          ‘setup()’.  Added package analysis to determine zip-safety if
          the ‘zip_safe’ flag is not given, and advise the author
          regarding what code might need changing.

        * Fixed the swapped ‘-d’ and ‘-b’ options of ‘bdist_egg’.

        * EasyInstall now automatically detects when an “unmanaged”
          package or module is going to be on ‘sys.path’ ahead of a
          package you’re installing, thereby preventing the newer
          version from being imported.  By default, it will abort
          installation to alert you of the problem, but there are also
          new options (‘--delete-conflicting’ and
          ‘--ignore-conflicts-at-my-risk’) available to change the
          default behavior.  (Note: this new feature doesn’t take effect
          for egg files that were built with older ‘setuptools’
          versions, because they lack the new metadata file required to
          implement it.)

        * The ‘easy_install’ distutils command now uses ‘DistutilsError’
          as its base error type for errors that should just issue a
          message to stderr and exit the program without a traceback.

        * EasyInstall can now be given a path to a directory containing
          a setup script, and it will attempt to build and install the
          package there.

        * EasyInstall now performs a safety analysis on module contents
          to determine whether a package is likely to run in zipped
          form, and displays information about what modules may be doing
          introspection that would break when running as a zipfile.

        * Added the ‘--always-unzip/-Z’ option, to force unzipping of
          packages that would ordinarily be considered safe to unzip,
          and changed the meaning of ‘--zip-ok/-z’ to “always leave
          everything zipped”.


File: setuptools.info,  Node: 0 5a8,  Next: 0 5a7,  Prev: 0 5a9,  Up: History<2>

9.470 0.5a8
===========

        * The “egg_info” command now always sets the distribution
          metadata to “safe” forms of the distribution name and version,
          so that distribution files will be generated with parseable
          names (i.e., ones that don’t include ‘-‘ in the name or
          version).  Also, this means that if you use the various
          ‘--tag’ options of “egg_info”, any distributions generated
          will use the tags in the version, not just egg distributions.

        * Added support for defining command aliases in distutils
          configuration files, under the “[aliases]” section.  To
          prevent recursion and to allow aliases to call the command of
          the same name, a given alias can be expanded only once per
          command-line invocation.  You can define new aliases with the
          “alias” command, either for the local, global, or per-user
          configuration.

        * Added “rotate” command to delete old distribution files, given
          a set of patterns to match and the number of files to keep.
          (Keeps the most recently-modified distribution files matching
          each pattern.)

        * Added “saveopts” command that saves all command-line options
          for the current invocation to the local, global, or per-user
          configuration file.  Useful for setting defaults without
          having to hand-edit a configuration file.

        * Added a “setopt” command that sets a single option in a
          specified distutils configuration file.

        * There is now a separate documentation page for setuptools;
          revision history that’s not specific to EasyInstall has been
          moved to that page.


File: setuptools.info,  Node: 0 5a7,  Next: 0 5a6,  Prev: 0 5a8,  Up: History<2>

9.471 0.5a7
===========

        * Added “upload” support for egg and source distributions,
          including a bug fix for “upload” and a temporary workaround
          for lack of .egg support in PyPI.


File: setuptools.info,  Node: 0 5a6,  Next: 0 5a5,  Prev: 0 5a7,  Up: History<2>

9.472 0.5a6
===========

        * Beefed up the “sdist” command so that if you don’t have a
          MANIFEST.in, it will include all files under revision control
          (CVS or Subversion) in the current directory, and it will
          regenerate the list every time you create a source
          distribution, not just when you tell it to.  This should make
          the default “do what you mean” more often than the distutils’
          default behavior did, while still retaining the old behavior
          in the presence of MANIFEST.in.

        * Fixed the “develop” command always updating .pth files, even
          if you specified ‘-n’ or ‘--dry-run’.

        * Slightly changed the format of the generated version when you
          use ‘--tag-build’ on the “egg_info” command, so that you can
          make tagged revisions compare `lower' than the version
          specified in setup.py (e.g.  by using ‘--tag-build=dev’).


File: setuptools.info,  Node: 0 5a5,  Next: 0 5a4,  Prev: 0 5a6,  Up: History<2>

9.473 0.5a5
===========

        * Added ‘develop’ command to ‘setuptools’-based packages.  This
          command installs an ‘.egg-link’ pointing to the package’s
          source directory, and script wrappers that ‘execfile()’ the
          source versions of the package’s scripts.  This lets you put
          your development checkout(s) on sys.path without having to
          actually install them.  (To uninstall the link, use use
          ‘setup.py develop --uninstall’.)

        * Added ‘egg_info’ command to ‘setuptools’-based packages.  This
          command just creates or updates the “projectname.egg-info”
          directory, without building an egg.  (It’s used by the
          ‘bdist_egg’, ‘test’, and ‘develop’ commands.)

        * Enhanced the ‘test’ command so that it doesn’t install the
          package, but instead builds any C extensions in-place, updates
          the ‘.egg-info’ metadata, adds the source directory to
          ‘sys.path’, and runs the tests directly on the source.  This
          avoids an “unmanaged” installation of the package to
          ‘site-packages’ or elsewhere.

        * Made ‘easy_install’ a standard ‘setuptools’ command, moving it
          from the ‘easy_install’ module to
          ‘setuptools.command.easy_install’.  Note that if you were
          importing or extending it, you must now change your imports
          accordingly.  ‘easy_install.py’ is still installed as a
          script, but not as a module.


File: setuptools.info,  Node: 0 5a4,  Next: 0 5a3,  Prev: 0 5a5,  Up: History<2>

9.474 0.5a4
===========

        * Setup scripts using setuptools can now list their dependencies
          directly in the setup.py file, without having to manually
          create a ‘depends.txt’ file.  The ‘install_requires’ and
          ‘extras_require’ arguments to ‘setup()’ are used to create a
          dependencies file automatically.  If you are manually creating
          ‘depends.txt’ right now, please switch to using these setup
          arguments as soon as practical, because ‘depends.txt’ support
          will be removed in the 0.6 release cycle.  For documentation
          on the new arguments, see the ‘setuptools.dist.Distribution’
          class.

        * Setup scripts using setuptools now always install using
          ‘easy_install’ internally, for ease of uninstallation and
          upgrading.

        * Added ‘--always-copy/-a’ option to always copy needed packages
          to the installation directory, even if they’re already present
          elsewhere on sys.path.  (In previous versions, this was the
          default behavior, but now you must request it.)

        * Added ‘--upgrade/-U’ option to force checking PyPI for latest
          available version(s) of all packages requested by name and
          version, even if a matching version is available locally.

        * Added automatic installation of dependencies declared by a
          distribution being installed.  These dependencies must be
          listed in the distribution’s ‘EGG-INFO’ directory, so the
          distribution has to have declared its dependencies by using
          setuptools.  If a package has requirements it didn’t declare,
          you’ll still have to deal with them yourself.  (E.g., by
          asking EasyInstall to find and install them.)

        * Added the ‘--record’ option to ‘easy_install’ for the benefit
          of tools that run ‘setup.py install --record=filename’ on
          behalf of another packaging system.)


File: setuptools.info,  Node: 0 5a3,  Next: 0 5a2,  Prev: 0 5a4,  Up: History<2>

9.475 0.5a3
===========

        * Fixed not setting script permissions to allow execution.

        * Improved sandboxing so that setup scripts that want a
          temporary directory (e.g.  pychecker) can still run in the
          sandbox.


File: setuptools.info,  Node: 0 5a2,  Next: 0 5a1,  Prev: 0 5a3,  Up: History<2>

9.476 0.5a2
===========

        * Fix stupid stupid refactoring-at-the-last-minute typos.  :(


File: setuptools.info,  Node: 0 5a1,  Next: 0 4a4,  Prev: 0 5a2,  Up: History<2>

9.477 0.5a1
===========

        * Added support for “self-installation” bootstrapping.  Packages
          can now include ‘ez_setup.py’ in their source distribution,
          and add the following to their ‘setup.py’, in order to
          automatically bootstrap installation of setuptools as part of
          their setup process:

               from ez_setup import use_setuptools
               use_setuptools()

               from setuptools import setup
               # etc...

        * Added support for converting ‘.win32.exe’ installers to eggs
          on the fly.  EasyInstall will now recognize such files by name
          and install them.

        * Fixed a problem with picking the “best” version to install
          (versions were being sorted as strings, rather than as parsed
          values)


File: setuptools.info,  Node: 0 4a4,  Next: 0 4a3,  Prev: 0 5a1,  Up: History<2>

9.478 0.4a4
===========

        * Added support for the distutils “verbose/quiet” and “dry-run”
          options, as well as the “optimize” flag.

        * Support downloading packages that were uploaded to PyPI (by
          scanning all links on package pages, not just the
          homepage/download links).


File: setuptools.info,  Node: 0 4a3,  Next: 0 4a2,  Prev: 0 4a4,  Up: History<2>

9.479 0.4a3
===========

        * Add progress messages to the search/download process so that
          you can tell what URLs it’s reading to find download links.
          (Hopefully, this will help people report out-of-date and
          broken links to package authors, and to tell when they’ve
          asked for a package that doesn’t exist.)


File: setuptools.info,  Node: 0 4a2,  Next: 0 4a1,  Prev: 0 4a3,  Up: History<2>

9.480 0.4a2
===========

        * Added ‘ez_setup.py’ installer/bootstrap script to make initial
          setuptools installation easier, and to allow distributions
          using setuptools to avoid having to include setuptools in
          their source distribution.

        * All downloads are now managed by the ‘PackageIndex’ class
          (which is now subclassable and replaceable), so that embedders
          can more easily override download logic, give download
          progress reports, etc.  The class has also been moved to the
          new ‘setuptools.package_index’ module.

        * The ‘Installer’ class no longer handles downloading, manages a
          temporary directory, or tracks the ‘zip_ok’ option.
          Downloading is now handled by ‘PackageIndex’, and ‘Installer’
          has become an ‘easy_install’ command class based on
          ‘setuptools.Command’.

        * There is a new ‘setuptools.sandbox.run_setup()’ API to invoke
          a setup script in a directory sandbox, and a new
          ‘setuptools.archive_util’ module with an ‘unpack_archive()’
          API. These were split out of EasyInstall to allow reuse by
          other tools and applications.

        * ‘setuptools.Command’ now supports reinitializing commands
          using keyword arguments to set/reset options.  Also, ‘Command’
          subclasses can now set their ‘command_consumes_arguments’
          attribute to ‘True’ in order to receive an ‘args’ option
          containing the rest of the command line.

        * Added support for installing scripts

        * Added support for setting options via distutils configuration
          files, and using distutils’ default options as a basis for
          EasyInstall’s defaults.

        * Renamed ‘--scan-url/-s’ to ‘--find-links/-f’ to free up ‘-s’
          for the script installation directory option.

        * Use ‘urllib2’ instead of ‘urllib’, to allow use of ‘https:’
          URLs if Python includes SSL support.


File: setuptools.info,  Node: 0 4a1,  Next: 0 3a4,  Prev: 0 4a2,  Up: History<2>

9.481 0.4a1
===========

        * Added ‘--scan-url’ and ‘--index-url’ options, to scan download
          pages and search PyPI for needed packages.


File: setuptools.info,  Node: 0 3a4,  Next: 0 3a3,  Prev: 0 4a1,  Up: History<2>

9.482 0.3a4
===========

        * Restrict ‘--build-directory=DIR/-b DIR’ option to only be used
          with single URL installs, to avoid running the wrong setup.py.


File: setuptools.info,  Node: 0 3a3,  Next: 0 3a2,  Prev: 0 3a4,  Up: History<2>

9.483 0.3a3
===========

        * Added ‘--build-directory=DIR/-b DIR’ option.

        * Added “installation report” that explains how to use
          ‘require()’ when doing a multiversion install or alternate
          installation directory.

        * Added SourceForge mirror auto-select (Contributed by Ian
          Bicking)

        * Added “sandboxing” that stops a setup script from running if
          it attempts to write to the filesystem outside of the build
          area

        * Added more workarounds for packages with quirky ‘install_data’
          hacks


File: setuptools.info,  Node: 0 3a2,  Next: 0 3a1,  Prev: 0 3a3,  Up: History<2>

9.484 0.3a2
===========

        * Added new options to ‘bdist_egg’ to allow tagging the egg’s
          version number with a subversion revision number, the current
          date, or an explicit tag value.  Run ‘setup.py bdist_egg
          --help’ to get more information.

        * Added subversion download support for ‘svn:’ and ‘svn+’ URLs,
          as well as automatic recognition of HTTP subversion URLs
          (Contributed by Ian Bicking)

        * Misc.  bug fixes


File: setuptools.info,  Node: 0 3a1,  Prev: 0 3a2,  Up: History<2>

9.485 0.3a1
===========

        * Initial release.


File: setuptools.info,  Node: Credits,  Next: Index,  Prev: History<2>,  Up: Top

10 Credits
**********

   * The original design for the ‘.egg’ format and the ‘pkg_resources’
     API was co-created by Phillip Eby and Bob Ippolito.  Bob also
     implemented the first version of ‘pkg_resources’, and supplied the
     macOS operating system version compatibility algorithm.

   * Ian Bicking implemented many early “creature comfort” features of
     easy_install, including support for downloading via Sourceforge and
     Subversion repositories.  Ian’s comments on the Web-SIG about WSGI
     application deployment also inspired the concept of “entry points”
     in eggs, and he has given talks at PyCon and elsewhere to inform
     and educate the community about eggs and setuptools.

   * Jim Fulton contributed time and effort to build automated tests of
     various aspects of ‘easy_install’, and supplied the doctests for
     the command-line ‘.exe’ wrappers on Windows.

   * Phillip J. Eby is the seminal author of setuptools, and first
     proposed the idea of an importable binary distribution format for
     Python application plug-ins.

   * Significant parts of the implementation of setuptools were funded
     by the Open Source Applications Foundation, to provide a plug-in
     infrastructure for the Chandler PIM application.  In addition, many
     OSAF staffers (such as Mike “Code Bear” Taylor) contributed their
     time and stress as guinea pigs for the use of eggs and setuptools,
     even before eggs were “cool”.  (Thanks, guys!)

   * Tarek Ziadé is the principal author of the Distribute fork, which
     re-invigorated the community on the project, encouraged renewed
     innovation, and addressed many defects.

   * Jason R. Coombs performed the merge with Distribute, maintaining
     the project for several years in coordination with the Python
     Packaging Authority (PyPA).


File: setuptools.info,  Node: Index,  Prev: Credits,  Up: Top

Index
*****