Wala shell

Advanced PHP File Manager

Server IP: 127.0.0.1 | PHP Version: 8.3.30 | Domains Hosted: 54

Name	Size	Last Modified	Actions
📁 ..	-	2026-03-27 02:58
📄 changed_keywords.rst New and Changed ``setup()`` Keywords ==================================== This document tracks historical differences between ``setuptools`` and ``distutils``. Since ``distutils`` was scheduled for removal from the standard library in Python 3.12, and ``setuptools`` started its adoption, these differences became less relevant. Please check :doc:`/references/keywords` for a complete list of keyword arguments that can be passed to the ``setuptools.setup()`` function and a their full description. .. tab:: Supported by both ``distutils`` and ``setuptoools`` ``name`` string ``version`` string ``description`` string ``long_description`` string ``long_description_content_type`` string ``author`` string ``author_email`` string ``maintainer`` string ``maintainer_email`` string ``url`` string ``download_url`` string ``packages`` list ``py_modules`` list ``scripts`` list ``ext_package`` string ``ext_modules`` list ``classifiers`` list ``distclass`` Distribution subclass ``script_name`` string ``script_args`` list ``options`` dictionary ``license`` string ``license_file`` string deprecated ``license_files`` list ``keywords`` string or list ``platforms`` list ``cmdclass`` dictionary ``data_files`` list deprecated ``package_dir`` dictionary ``requires`` string or list deprecated ``obsoletes`` list deprecated ``provides`` list .. tab:: Added or changed by ``setuptoools`` ``include_package_data`` bool ``exclude_package_data`` dictionary ``package_data`` dictionary ``zip_safe`` bool ``install_requires`` string or list ``entry_points`` dictionary ``extras_require`` dictionary ``python_requires`` string ``setup_requires`` string or list deprecated ``dependency_links`` list deprecated ``namespace_packages`` list ``test_suite`` string or function deprecated ``tests_require`` string or list deprecated ``test_loader`` class deprecated ``eager_resources`` list ``project_urls`` dictionary	2.13 KB	2022-11-24 06:08
📄 commands.rst =============================== Running ``setuptools`` commands =============================== Historically, ``setuptools`` allowed running commands via a ``setup.py`` script at the root of a Python project, as indicated in the examples below:: python setup.py --help python setup.py --help-commands python setup.py --version python setup.py sdist python setup.py bdist_wheel You could also run commands in other circumstances: * ``setuptools`` projects without ``setup.py`` (e.g., ``setup.cfg``-only):: python -c "from setuptools import setup; setup()" --help * ``distutils`` projects (with a ``setup.py`` importing ``distutils``):: 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. .. warning:: While it is perfectly fine that users write ``setup.py`` files to configure a package build (e.g. to specify binary extensions or customize commands), on recent versions of ``setuptools``, running ``python setup.py`` directly as a script is considered deprecated. This also means that users should avoid running commands directly via ``python setup.py <command>``. If you want to create :term:`sdist <Source Distribution (or "sdist")>` or :term:`wheel` distributions the recommendation is to use the command line tool provided by :pypi:`build`:: pip install build # needs to be installed first python -m build # builds both sdist and wheel python -m build --sdist python -m build --wheel Build will automatically download ``setuptools`` and build the package in an isolated environment. You can also specify specific versions of ``setuptools``, by setting the :doc:`build requirements in pyproject.toml </build_meta>`. If you want to install a package, you can use :pypi:`pip` or :pypi:`installer`:: pip install /path/to/wheel/file.whl pip install /path/to/sdist/file.tar.gz pip install . # replacement for python setup.py install pip install --editable . # replacement for python setup.py develop pip install installer # needs to be installed first python -m installer /path/to/wheel/file.whl ----------------- Command Reference ----------------- .. _alias: ``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 `configuration file options`_ (listed under the `saveopts`_ 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. ``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 `egg_info`_ 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. .. _develop: ``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. .. _egg_info: ``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 :ref:`Adding new EGG-INFO Files` 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``. 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 :ref:`Specifying Your Project's Version` 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: 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. ``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.) .. _rotate: ``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 .. _saveopts: ``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 `configuration file options`_ 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. 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 `alias`_ and `setopt`_ commands. .. _setopt: ``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 `configuration file options`_ (listed under the `saveopts`_ command, above) to determine which distutils configuration file the option will be added to (or removed from). .. _test: ``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 <https://tox.readthedocs.io>`_. 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 :ref:`test_loader <test_loader>` 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. .. _upload: ``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 <https://pypi.org/p/twine>`_ 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 <https://packaging.python.org/tutorials/packaging-projects/#uploading-the-distribution-archives>`_.	28.98 KB	2022-11-24 06:08
📄 dependency_links.rst Specifying dependencies that aren't in PyPI via ``dependency_links`` ==================================================================== .. 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 if 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 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: .. tab:: setup.cfg .. code-block:: ini [options] #... dependency_links = http://peak.telecommunity.com/snapshots/ .. tab:: setup.py .. code-block:: python setup( ..., dependency_links=[ "http://peak.telecommunity.com/snapshots/", ], )	2.79 KB	2022-11-24 06:08
📁 distutils	-	2026-03-27 02:58
📄 distutils-legacy.rst Porting from Distutils ====================== Setuptools and the PyPA have a `stated goal <https://github.com/pypa/packaging-problems/issues/127>`_ to make Setuptools the reference API for distutils. Since the 60.0.0 release, Setuptools includes a local, vendored copy of distutils (from late copies of CPython) that is enabled by default. To disable the use of this copy of distutils when invoking setuptools, set the environment variable: SETUPTOOLS_USE_DISTUTILS=stdlib .. warning:: Please note that this also affects how ``distutils.cfg`` files inside stdlib's ``distutils`` package directory are processed. Unless ``SETUPTOOLS_USE_DISTUTILS=stdlib``, they will have no effect on the build process. You can still use a global user config file, ``~/.pydistutils.cfg`` (POSIX) or ``%USERPROFILE%/pydistutils.cfg`` (Windows), or use the environment variable :doc:`DIST_EXTRA_CONFIG <deprecated/distutils/configfile>` to point to another supplementary configuration file. 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.command.{build_clib,build_ext,build_py,sdist}`` → ``setuptools.command.`` ``distutils.log`` → :mod:`logging` (standard library) ``distutils.version.`` → :doc:`packaging.version.* <packaging:version>` ``distutils.errors.`` → ``setuptools.errors.`` [#errors]_ Migration advice is also provided by :pep:`PEP 632 <632#migration-advice>`. If a project relies on uses of ``distutils`` that do not have a suitable replacement above, please search the `Setuptools issue tracker <https://github.com/pypa/setuptools/issues/>`_ 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. .. [#errors] Please notice errors related to the command line usage of ``setup.py``, such as ``DistutilsArgError``, are intentionally not exposed by setuptools, since this is considered a deprecated practice.	2.31 KB	2022-11-24 06:08
📄 easy_install.rst ============ 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 <http://mail.python.org/pipermail/distutils-sig/>`_. (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.) Using "Easy Install" ==================== .. _installation instructions: Installing "Easy Install" ------------------------- Please see the :pypi:`setuptools` on the package index 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 `Custom Installation Locations`_ 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 <http://ntlmaps.sf.net/>`_, 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 `restricting downloads with --allow-hosts`_ and `command-line options`_ for more details.) 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 `Custom Installation Locations`_ 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 `Custom Installation Locations`_ for more details. Windows Notes ~~~~~~~~~~~~~ Installing setuptools will provide an ``easy_install`` command according to the techniques described in `Executables and Launchers`_. If the ``easy_install`` command is not available after installation, that section provides details on how to configure Windows to make the commands available. 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`__). __ http://peak.telecommunity.com/DevCenter/PythonEggs 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 `Editing and Viewing Source Packages`_ 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 `Configuration Files`_, 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. 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 `Uninstalling Packages`_, below. 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. 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. 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 <http://docutils.sf.net/>`_ 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.) 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 `Command-Line Options`_ and `Configuration Files`_. During installation, pass command line options (such as ``--script-dir``) to control where scripts will be installed. 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". Natural Script Launcher ~~~~~~~~~~~~~~~~~~~~~~~ EasyInstall also supports deferring to an external launcher such as `pylauncher <https://bitbucket.org/pypa/pylauncher>`_ 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. Tips & Techniques ----------------- 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. 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 `Command-Line Options`_ 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 `configuration files`_ and adding: .. code-block:: ini [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. 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. 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. 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 `configuration files`_: .. code-block:: ini [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 `Command-Line Options`_, below, and also the section on `Package Index "API"`_. 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. 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. Controlling Build Options ~~~~~~~~~~~~~~~~~~~~~~~~~ EasyInstall respects standard distutils `Configuration Files`_, 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: .. code-block:: ini [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 `Configuration Files`_ below for a list of the standard configuration file locations, and links to more documentation on using distutils configuration files. 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 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! 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.) Reference Manual ================ 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: .. code-block:: ini [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 <https://docs.python.org/install/index.html#inst-config-files>`_. 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. 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` 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 `Configuration Files`_, 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 `Editing and Viewing Source Packages`_ 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 `Editing and Viewing Source Packages`_, 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 `configuration files`_, 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. .. _non-root installation: 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]_. `Use the "--user" option`_ `Use the "--user" option and customize "PYTHONUSERBASE"`_ `Use "virtualenv"`_ .. [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`_. .. _PEP-370: http://www.python.org/dev/peps/pep-0370/ 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 [3]_. 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. .. [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. 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. 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 :pypi:`virtualenv` documentation for more details. 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.	50.84 KB	2022-11-24 06:08
📄 functionalities.rst "Eggsecutable" Scripts ---------------------- .. deprecated:: 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.	1.42 KB	2022-11-24 06:08
📄 index.rst ====================================================== 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. .. toctree:: :maxdepth: 1 changed_keywords dependency_links python_eggs easy_install zip_safe resource_extraction distutils/index distutils-legacy functionalities commands	863 B	2022-11-24 06:08
📄 python_eggs.rst ===================================== The Internal Structure of Python Eggs ===================================== STOP! This is not the first document you should read! ---------------------- 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.) 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.) 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 `Standard Metadata`_, 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. 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.) 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. ----------------- 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. ``.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. Dependency Metadata =================== ``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. ``setup_requires.txt`` ---------------------- Much like ``requires.txt`` except represents the requirements specified by the ``setup_requires`` parameter to the Distribution. ``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. ``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. ``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. ``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. 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 `script wrappers`_, see the section below on `Installation and Path Management Issues`_. Zip Support Metadata ==================== ``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 `Zip File Issues`_ section below for more information on library and resource extraction from ``.egg`` files. ``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 `Zip File Issues`_ section below. ``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. ``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.) ``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. ------------------------------ Other Technical Considerations ------------------------------ 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. 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. 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. 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 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.	30.22 KB	2022-11-24 06:08
📄 resource_extraction.rst .. _Automatic Resource Extraction: Automatic Resource Extraction ============================= In a modern setup, Python packages are usually installed as directories, and all the files can be found on deterministic locations on the disk. This means that most of the tools expect package resources to be "real" files. There are a few occasions however that packages are loaded in a different way (e.g., from a zip file), which is incompatible with the assumptions mentioned above. Moreover, a package developer may also include non-extension native libraries or other files that C extensions may expect to be able to access. In these scenarios, the use of :mod:`importlib.resources` is recommended. Old implementations (prior to the advent of :mod:`importlib.resources`) and long-living projects, however, may still rely on the library ``pkg_resources`` to access these files. If you have to support such systems, or want to provide backward compatibility for ``pkg_resources``, you may need to add an special configuration to ``setuptools`` when packaging a project. This can be done by listing as ``eager_resources`` (argument to ``setup()`` in ``setup.py`` or field in ``setup.cfg``) all the files that need to 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``/``setuptools``-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.	2.98 KB	2022-11-24 06:08
📄 zip_safe.rst Understanding the ``zip_safe`` flag =================================== The ``zip_safe`` flag is a ``setuptools`` configuration mainly associated with the ``egg`` distribution format (which got replaced in the ecosystem by the newer ``wheel`` format) and the ``easy_install`` command (deprecated in ``setuptools`` v58.3.0). It is very unlikely that the values of ``zip_safe`` will affect modern deployments that use :pypi:`pip` for installing packages. Moreover, new users of ``setuptools`` should not attempt to create egg files using the deprecated ``build_egg`` command. Therefore, this flag is considered obsolete. This document, however, describes what was the historical motivation behind this flag, and how it was used. Historical Motivation --------------------- 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. In the past, ``setuptools`` would install a project distributed as a zipfile or a directory (via the ``easy_install`` command or ``python setup.py install``), the default choice being determined by the project's ``zip_safe`` flag. How the ``zip_safe`` flag was used? ----------------------------------- To set this flag, a developer would pass a boolean value for the ``zip_safe`` argument to the ``setup()`` function, or omit it. When omitted, the ``bdist_egg`` command would analyze the project's contents to see if it could detect any conditions that preventing the project from working in a zipfile. This was extremely conservative: ``bdist_egg`` would consider the project unsafe if it contained any C extensions or datafiles whatsoever. This does not mean that the project couldn't or wouldn't work as a zipfile! It just means that the ``bdist_egg`` authors were not yet comfortable asserting that the project would work. If the project did not contain any C or data files, and did not attempt to perform ``__file__`` or ``__path__`` introspection or source code manipulation, then there was an extremely solid chance the project will work when installed as a zipfile. (And if the project used ``pkg_resources`` for all its data file access, then C extensions and other data files shouldn't be a problem at all. See the :ref:`Accessing Data Files at Runtime` section for more information.) The developer could manually set ``zip_safe`` to ``True`` to perform tests, or to override the default behaviour (after checking all the warnings and understanding the implications), this would allow ``setuptools`` to install the project as a zip file. Alternatively, by setting ``zip_safe`` to ``False``, developers could force ``setuptools`` to always install the project as a directory. Modern ways of loading packages from zip files ---------------------------------------------- Currently, popular Python package installers (such as :pypi:`pip`) and package indexes (such as PyPI_) consider that distribution packages are always installed as a directory. It is however still possible to load packages from zip files added to :obj:`sys.path`, thanks to the :mod:`zipimport` module and the :mod:`importlib` machinery provided by Python standard library. When working with modules loaded from a zip file, it is important to keep in mind that values of ``__file__`` and ``__path__`` might not work as expected. Please check the documentation for :mod:`importlib.resources`, if file locations are important for your use case. .. _PyPI: https://pypi.org	3.57 KB	2022-11-24 06:08

Terminal