diff options
Diffstat (limited to 'docs/deprecated')
| -rw-r--r-- | docs/deprecated/index.rst | 2 | ||||
| -rw-r--r-- | docs/deprecated/resource_extraction.rst | 54 | ||||
| -rw-r--r-- | docs/deprecated/zip_safe.rst | 74 |
3 files changed, 130 insertions, 0 deletions
diff --git a/docs/deprecated/index.rst b/docs/deprecated/index.rst index 8169b3b7..96bdb313 100644 --- a/docs/deprecated/index.rst +++ b/docs/deprecated/index.rst @@ -16,6 +16,8 @@ objectives. changed_keywords python_eggs easy_install + zip_safe + resource_extraction distutils/index distutils-legacy functionalities diff --git a/docs/deprecated/resource_extraction.rst b/docs/deprecated/resource_extraction.rst new file mode 100644 index 00000000..19190baf --- /dev/null +++ b/docs/deprecated/resource_extraction.rst @@ -0,0 +1,54 @@ +.. _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. diff --git a/docs/deprecated/zip_safe.rst b/docs/deprecated/zip_safe.rst new file mode 100644 index 00000000..1b299b3c --- /dev/null +++ b/docs/deprecated/zip_safe.rst @@ -0,0 +1,74 @@ +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 an 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 |